Configurations

Overview

Developers who wish to register APIs in the fabric ecosystem should review the API Resources configurations below. Application developers that are planning to use Fabric.Identity for authentication should review suggested configurations below for Identity Resources, Client Registration, and External Identity Providers.

API Resources

In order for Fabric.Identity to protect an API, the API resource must first be registered with with Fabric.Identity using the /api/apiresource endpoint.

When registering an API with Fabric.Identity, you need to provide a name that uniquely identifies the API, a list of Scopes that are available from your API, and optionally a list of user claims that you would like Fabric.Identity to pass to your API.

Client applications can request access to those scopes and user claims, and if granted, Fabric.Identity will embed them in the access token returned to the client application. The Client application in turn sends that access token in the header of a request to your API and you can check for the presence of the appopriate scope/user claims before fulfilling the request.

For a deeper dive on API Resources see IdentityServer4's documentation.

Identity Resources

Identity Resources are information about a user that Fabric.Identity protects, and each Identity resource represents a set of claims about a user such as group membership or email address for the user.

By default Fabric.Identity comes with the following Identity Resources:

• OpenId - contains the subject identifier claim, which uniquely identifies the user.
• Profile - contains the name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at claims.
• Email - contains the email claim
• Address - contains the address claim
• Fabric.Profile - contains the group and role claims

The above Identity Resources can be requested as allowed scopes for a client application. In addition, the claims outlined can be set as requested user claims for a protected API.

Note that since Fabric.Identity does not have a local user store these claims being populated are dependent on what the third party identity provider supports and has populated.

For a deeper dive on Identity Resources see IdentityServer4's documentation.

Clients

Clients are applications that leverage Fabric.Identity's authentication as a service as well as interact with APIs and Identity resources protected by Fabric.Identity.

Client applications are registered via the /api/client endpoint.

Key things to keep in mind when registering Clients are:

• Grant Type: The grant type specifies how the client application will interact with Fabric.Identity. For a deep discussion on grant types refer to IdentityServer4's documentation on the subject.
• AllowedScopes: This is the list of scopes that a client is allowed to access. If a client requests a scope that is not in the allowed scopes list, Fabric.Identity will return an invalid_client error.
• RedirectUris: This is a list of allowed URI's that Fabric.Identity will return tokens or authorization codes to. Again, if a requested redirect URI specified by the client is not set in the config stored in Fabric.Identity, an invalid_client error will be returned.

See more details about Clients in IdentityServer4's documentation.

External Identity Providers

External Identity providers are external services that Fabric.Identity will delegate authentication to. Fabric.Identity supports Active Directory as well as any OpenID Connect provider. See our installation guide for how to configure Fabric.Identity to setup AD integration.

To add an OpenID Connect external identity provider you can add the configuration to the "ExternalIdProviderSettings" section in the appsettings.json file.

The following is an example on how to configure Azure Active Directory as an external identity provider:

"ExternalIdProviderSettings": {
    "ExternalIdProviders": [
        {
            "Type":"OpenIDConnect",
            "DisplayName":"Azure Active Directory",
            "Authority":"http://example.com",
            "ClientId":"[your client id]",
            "ClientSecret":"[your client secret]",
            "ResponseType":"code id_token token",
            "Scope":[ "openid", "profile" ]
        }]
  }

Important fields above are:

• DisplayName: The external identity provider's name as shown to the end user.
• Authority: The Url for the external identity provider that provides access and identity tokens.
• ClientId: The client id as provided by the external identity provider.
• ClientSecret: The client secret as provided by the external identity provider.
• ResponseType: The type of response you want to receive from the external identity provider, valid values are code, token, id_token. These map to the grant types discussed above.

You can optionally specify multiple external identity providers and Fabric.Identity will allow the end user to choose which identity provider to authenticate with, using the DisplayName value as the name that is shown to the user to describe the identity provider.