Criando seu primeiro Identity Server

Situação atual do IdentityServer4

Antes de seguir, existe um ponto importante sobre manutenção. Segundo o repositório oficial, o IdentityServer4 saiu de suporte junto com o .NET Core 3.1, em 13 de dezembro de 2022.

Depois disso, os criadores do projeto continuaram o trabalho em um produto comercial chamado Duende IdentityServer. Além disso, o repositório original foi arquivado e hoje é somente leitura.

Portanto, este tutorial mantém o IdentityServer4 porque ele é a base do artigo e da série. Contudo, para um projeto novo em produção, avalie o Duende IdentityServer, que pode exigir licença paga, ou alternativas como o OpenIddict.

Mesmo assim, montar o primeiro Identity Server com o IdentityServer4 continua sendo uma ótima forma de aprender. Afinal, os conceitos de clientes, escopos, recursos e discovery document são os mesmos nas ferramentas mais recentes.

Instalando os templates

Para instalar os templates oficiais do IdentityServer4, execute o comando abaixo no terminal. Ele baixa o pacote do NuGet e registra os novos modelos no dotnet new.

dotnet new -i IdentityServer4.Templates

Vale uma observação sobre a sintaxe. A partir do SDK do .NET 7, o comando recomendado passou a ser dotnet new install, enquanto a opção -i virou uma forma antiga que ainda funciona.

# Sintaxe equivalente nos SDKs mais novos
dotnet new install IdentityServer4.Templates

Em seguida, você pode listar os modelos instalados com dotnet new --list. Os nomes curtos começam com is4, o que facilita encontrar cada um.

Templates disponíveis

O pacote traz vários templates, cada um pensado para um cenário diferente. A tabela a seguir resume o propósito de cada um, de acordo com o repositório oficial.

Neste artigo, vamos começar pelo mais básico, o is4empty. Particularmente, uso bastante esse modelo, porque ele entrega só o essencial e deixa claro o que cada parte faz.

Arquivos gerados no primeiro Identity Server

O template cria uma estrutura pequena e fácil de entender. Na prática, o primeiro Identity Server tem apenas quatro arquivos que importam neste momento.

• Program.cs: o ponto de entrada da aplicação, que configura o host web.
• Startup.cs: onde o IdentityServer é registrado e adicionado ao pipeline.
• Config.cs: onde ficam os recursos, os escopos e os clientes.
• Properties\launchSettings.json: onde ficam a porta e o perfil de execução.

A documentação chama a abordagem do Config.cs de configuração como código. Ou seja, você descreve clientes e escopos em classes C#, sem banco de dados, o que é ideal para começar.

Entendendo o Startup.cs

O Startup.cs é o coração do primeiro Identity Server. Ele registra o serviço, informa de onde vêm as configurações e liga o middleware.

public class Startup
{
    public IWebHostEnvironment Environment { get; }

    public Startup(IWebHostEnvironment environment)
    {
        Environment = environment;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        // Registra o IdentityServer com as configurações em memória
        var builder = services.AddIdentityServer(options =>
            {
                options.EmitStaticAudienceClaim = true;
            })
            .AddInMemoryIdentityResources(Config.IdentityResources)
            .AddInMemoryApiScopes(Config.ApiScopes)
            .AddInMemoryClients(Config.Clients);

        // Chave de assinatura apenas para desenvolvimento
        builder.AddDeveloperSigningCredential();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (Environment.IsDevelopment())
            app.UseDeveloperExceptionPage();

        // Expõe os endpoints de OpenID Connect e OAuth 2.0
        app.UseIdentityServer();
    }
}

O método AddIdentityServer registra os serviços do framework no container de injeção de dependência. Em seguida, os métodos AddInMemory carregam recursos, escopos e clientes direto das listas do Config.cs.

Já o UseIdentityServer adiciona o IdentityServer ao pipeline de requisições. Com isso, o servidor passa a responder em endpoints padronizados, como o /connect/token.

Entendendo o Config.cs

No template vazio, o Config.cs começa quase sem conteúdo. Ele declara apenas o recurso de identidade obrigatório do OpenID Connect e deixa as outras listas vazias.

public static class Config
{
    // Informações de identidade que podem ser entregues ao cliente
    public static IEnumerable<IdentityResource> IdentityResources =>
        new IdentityResource[]
        {
            new IdentityResources.OpenId()
        };

    // Escopos que representam as APIs protegidas
    public static IEnumerable<ApiScope> ApiScopes =>
        new ApiScope[] { };

    // Aplicações autorizadas a pedir tokens
    public static IEnumerable<Client> Clients =>
        new Client[] { };
}

Os recursos de identidade descrevem dados do usuário, como nome e e-mail. Por outro lado, os escopos de API representam funcionalidades protegidas que um cliente pode acessar com um token.

Os clientes, por fim, são as aplicações que vão pedir tokens ao servidor. Nos próximos artigos, vamos preencher essas listas e conectar aplicativos e APIs ao primeiro Identity Server.

A chave de assinatura de desenvolvimento

Todo token emitido precisa de uma assinatura digital. Assim, quem recebe o token consegue confirmar que ele veio do servidor certo e que ninguém alterou o conteúdo.

O método AddDeveloperSigningCredential resolve isso de forma simples durante o desenvolvimento. Na primeira execução, o IdentityServer4 gera um arquivo chamado tempkey.jwk com a chave usada nas assinaturas.

Esse arquivo não precisa ir para o controle de versão, porque o servidor o recria se ele não existir. No entanto, em produção você deve trocar esse método por uma chave real, carregada com AddSigningCredential.

O que observar no discovery document

A resposta é um JSON com várias propriedades. Algumas delas merecem atenção logo nesta primeira validação.

• issuer: o endereço que identifica o servidor e aparece dentro dos tokens.
• jwks_uri: o endereço onde clientes e APIs buscam a chave pública de validação.
• authorization_endpoint: o endpoint usado nos fluxos com login interativo.
• token_endpoint: o endpoint que emite os tokens de acesso.
• scopes_supported: a lista de escopos que o servidor conhece.
• grant_types_supported: os fluxos de concessão que o servidor aceita.

Se o JSON aparecer, então o seu primeiro Identity Server está no ar. Além disso, você já pode notar o escopo openid na lista, porque ele veio do Config.cs.

O discovery document também é o que as bibliotecas cliente usam para se configurar sozinhas. Por exemplo, a biblioteca IdentityModel lê esse endpoint para descobrir onde pedir tokens.

Template não encontrado

Se o comando dotnet new is4empty responder que o template não existe, a instalação não foi concluída. Nesse caso, rode novamente a instalação e confira a lista com dotnet new --list.

Também vale verificar se você está sem acesso ao NuGet, por exemplo atrás de um proxy corporativo. Afinal, o pacote de templates vem de lá.

Porta já em uso

Outra situação comum é a porta 5001 já estar ocupada por outra aplicação. Então, o Kestrel não consegue iniciar e mostra um erro de endereço em uso.

Para resolver, encerre a outra aplicação ou altere a porta no launchSettings.json. Lembre apenas de usar a nova porta quando acessar o discovery document.

Erro de certificado

Quando o navegador mostra um aviso de conexão não segura, o certificado de desenvolvimento ainda não é confiável. Como vimos, o comando dotnet dev-certs https --trust resolve esse ponto.

Em sistemas Linux, a confiança no certificado pode exigir passos extras, conforme a distribuição. Por isso, consulte a documentação do ASP.NET Core sobre HTTPS caso o aviso continue.