Welcome to IdentityServer4¶

The big Picture¶

Most modern applications look more or less like this:

The typical interactions are:

• Browsers communicate with web applications
• Web applications communicate with web APIs (sometimes on their own, sometimes on behalf of a user)
• Browser-based applications communicate with web APIs
• Native applications communicate with web APIs
• Server-based applications communicate with web APIs
• Web APIs communicate with web APIs (sometimes on their own, sometimes on behalf of a user)

Typically each and every layer (front-end, middle-tier and back-end) has to protect resources and implement authentication and/or authorization – and quite typically against the same user store.

This is why we don’t implement these fundamental security functions in the business applications/endpoints themselves, but rather outsource that critical functionality to a service - the security token service.

This leads to the following security architecture and usage of protocols:

This divides the security concerns into two parts.

Terminology¶

The specs, documentation and object model use a certain terminology that you should be aware of.

Supported Specifications¶

IdentityServer implements the following specifications:

• OpenID Connect Core 1.0 (spec)
• OpenID Connect Discovery 1.0 (spec)
• OpenID Connect Session Management 1.0 - draft 22 (spec)
• OpenID Connect HTTP-based Logout 1.0 - draft 03 (spec)
• OAuth 2.0 (RFC 6749)
• OAuth 2.0 Bearer Token Usage (RFC 6750)
• OAuth 2.0 Multiple Response Types (spec)
• OAuth 2.0 Form Post Response Mode (spec)
• OAuth 2.0 Token Revocation (RFC 7009)
• OAuth 2.0 Token Introspection (RFC 7662)

Packaging and Builds¶

IdentityServer consists of a number of nuget packages.

Defining Scopes¶

The first thing you typically define in your system are the resources that you want to protect. That could be identity information of your users like profile data or email addresses or access to APIs.

public class Scopes
{
    public static IEnumerable<Scope> Get()
    {
        return new List<Scope>
        {
            StandardScopes.OpenId
        };
    }
}

public class Scopes
{
    public static IEnumerable<Scope> Get()
    {
        return new List<Scope>
        {
            StandardScopes.OpenId,
            StandardScopes.Profile,
            StandardScopes.Email,
            StandardScopes.Address,
            StandardScopes.OfflineAccess
        };
    }
}

new Scope
{
    Name = "tenant.info",
    DisplayName = "Tenant Information",
    Type = ScopeType.Identity,

    Claims = new List<ScopeClaim>
    {
        new ScopeClaim("tenantid"),
        new ScopeClaim("subscriptionid")
    }
}

new Scope
{
    Name = "api1",
    DisplayName = "API #1",
    Description = "API 1",
    Type = ScopeType.Resource
}

Defining Clients¶

Clients represent applications that can request tokens from your identityserver.

The details vary, but you typically define the following common settings for a client:

• a unique client ID
• a secret if needed
• the allowed interactions with the token service (called a grant type)
• a network location where identity and/or access token gets sent to (called a redirect URI)
• a list of scopes (aka resources) the client is allowed to access

public class Clients
{
    public static IEnumerable<Client> Get()
    {
        return new List<Client>
        {
            new Client
            {
                ClientId = "service.client",
                ClientSecrets = new List<Secret>
                {
                    new Secret("secret".Sha256())
                },

                AllowedGrantTypes = GrantTypes.ClientCredentials,

                AllowedScopes = new List<string>
                {
                    "api1", "api2"
                }
            };
        }
    }
}

var jsClient = new Client
{
    ClientId = "js",
    ClientName = "JavaScript Client",
    ClientUri = "http://identityserver.io",

    AllowedGrantTypes = GrantTypes.Implicit,
    AllowAccessTokensViaBrowser = true,

    RedirectUris = new List<string>
    {
        "http://localhost:7017/index.html",
    },
    PostLogoutRedirectUris = new List<string>
    {
        "http://localhost:7017/index.html",
    },
    AllowedCorsOrigins = new List<string>
    {
        "http://localhost:7017"
    },

    AllowedScopes = new List<string>
    {
        StandardScopes.OpenId.Name,
        StandardScopes.Profile.Name,
        StandardScopes.Email.Name,
        "api1", "api2"
    },
};

var mvcClient = new Client
{
    ClientId = "mvc",
    ClientName = "MVC Client",
    ClientSecrets = new List<Secret>
    {
        new Secret("secret".Sha256())
    },
    ClientUri = "http://identityserver.io",

    AllowedGrantTypes = GrantTypes.Hybrid,

    RedirectUris = new List<string>
    {
        "http://localhost:21402/signin-oidc"
    },
    PostLogoutRedirectUris = new List<string>
    {
        "http://localhost:21402/"
    },
    LogoutUri = "http://localhost:21402/signout-oidc",

    AllowedScopes = new List<string>
    {
        StandardScopes.OpenId.Name,
        StandardScopes.Profile.Name,
        StandardScopes.OfflineAccess.Name,

        "api1", "api2",
    },
};

Scope¶

The Scope class models a resource in your system.

• Enabled

  Indicates if scope is enabled and can be requested. Defaults to true.

• Name

  The unique name of the scope. This is the value a client will use to request the scope.

• DisplayName

  Display name for consent screen.

• Description

  • Description for the consent screen.

• Required

  Specifies whether the user can de-select the scope on the consent screen. Defaults to false.

• ScopeSecrets

  Adds a secret to scope for accessing the the introspection endpoint - see also [here](secrets.html).

• AllowUnrestrictedIntrospection

  Allows this scope to see all other scopes in the access token when using the introspection endpoint

• Emphasize

  Specifies whether the consent screen will emphasize this scope. Use this setting for sensitive or important scopes. Defaults to false.

• Type

  Either Identity (OpenID Connect related) or Resource (OAuth2 resources). Defaults to Resource.

• Claims

  List of user claims that should be included in the identity (identity scope) or access token (resource scope).

• IncludeAllClaimsForUser

  If enabled, all claims for the user will be included in the token. Defaults to false.

• ClaimsRule

  Rule for determining which claims should be included in the token (this is implementation specific)

• ShowInDiscoveryDocument

  Specifies whether this scope is shown in the discovery document. Defaults to true.

Scope can also specify claims that go into the corresponding token - the ScopeClaim class has the following properties:

• Name

  Name of the claim

• Description

  Description of the claim

• AlwaysIncludeInIdToken

  Specifies whether this claim should always be present in the identity token (even if an access token has been requested as well). Applies to identity scopes only. Defaults to false.

Client¶

The Client class models an OpenID Connect or OAuth2 client - e.g. a native application, a web application or a JS-based application.

• Enabled

  Specifies if client is enabled. Defaults to true.

• ClientId

  Unique ID of the client

• ClientSecrets

  List of client secrets - credentials to access the token endpoint.

• ClientName

  Client display name (used for logging and consent screen)

• ClientUri

  URI to further information about client (used on consent screen)

• LogoUri

  URI to client logo (used on consent screen)

• RequireConsent

  Specifies whether a consent screen is required. Defaults to true.

• AllowRememberConsent

  Specifies whether user can choose to store consent decisions. Defaults to true.

• AllowedGrantTypes

  Specifies the grant types the client is allowed to use. Use the GrantTypes class for common combinations.

• RedirectUris

  Specifies the allowed URIs to return tokens or authorization codes to

• PostLogoutRedirectUris

  Specifies allowed URIs to redirect to after logout

• LogoutUri

  Specifies logout URI at client for HTTP based logout

• LogoutSessionRequired

  Specifies if the user’s session id should be sent to the LogoutUri. Defaults to true.

• RequireSignOutPrompt

  Specifies if the client will always show a confirmation page for sign-out. Defaults to false.

• AllowedScopes

  By default a client has no access to any scopes - either specify the scopes explicitly here (recommended) - or set AllowAccessToAllScopes to true.

• AllowAccessTokensViaBrowser

  Specifies whether this client is allowed to request access tokens via the browser. This is useful to harden flows that allow multiple response types (e.g. by disallowing a hybrid flow client that is supposed to use code id_token to add the token response type and thus leaking the token to the browser.

• IdentityTokenLifetime

  Lifetime to identity token in seconds (defaults to 300 seconds / 5 minutes)

• AccessTokenLifetime

  Lifetime of access token in seconds (defaults to 3600 seconds / 1 hour)

• AuthorizationCodeLifetime

  Lifetime of authorization code in seconds (defaults to 300 seconds / 5 minutes)

• AbsoluteRefreshTokenLifetime

  Maximum lifetime of a refresh token in seconds. Defaults to 2592000 seconds / 30 days

• SlidingRefreshTokenLifetime

  Sliding lifetime of a refresh token in seconds. Defaults to 1296000 seconds / 15 days

• RefreshTokenUsage

  • ReUse: the refresh token handle will stay the same when refreshing tokens
  • OneTime: the refresh token handle will be updated when refreshing tokens

• RefreshTokenExpiration

  • Absolute: the refresh token will expire on a fixed point in time (specified by the AbsoluteRefreshTokenLifetime)
  • Sliding: when refreshing the token, the lifetime of the refresh token will be renewed (by the amount specified in SlidingRefreshTokenLifetime). The lifetime will not exceed AbsoluteRefreshTokenLifetime.

• UpdateAccessTokenClaimsOnRefresh

  Gets or sets a value indicating whether the access token (and its claims) should be updated on a refresh token request.

• AccessTokenType

  Specifies whether the access token is a reference token or a self contained JWT token (defaults to Jwt).

• EnableLocalLogin

  Specifies if this client can use local accounts, or external IdPs only. Defaults to true.

• IdentityProviderRestrictions

  Specifies which external IdPs can be used with this client (if list is empty all IdPs are allowed). Defaults to empty.

• IncludeJwtId

  Specifies whether JWT access tokens should have an embedded unique ID (via the jti claim).

• AllowedCorsOrigins

  If specified, will be used by the default CORS policy service implementations (In-Memory and EF) to build a CORS policy for JavaScript clients.

• Claims

  Allows settings claims for the client (will be included in the access token).

• AlwaysSendClientClaims

  If set, the client claims will be sent for every flow. If not, only for client credentials flow (default is false)

• PrefixClientClaims

  If set, all client claims will be prefixed with client_ to make sure they don’t accidentally collide with user claims. Default is true.