Skip to main content

Identity Provider

IdP Configuration​

The IdP Configuration is used to declare trusted identity providers that can be used to authenticate end users. Actors in the system can be associated to these configuration entries and with their respective subject or username. This allows the Akkess system to cross verify the credentials of a caller when they try to authenticate themselves.

Attributes:

  • key - The IdP key is used to identify the IdP configuration in Akkess. When an actor is assigned with an IdP affiliation the key is used to identify which IdP configuration to use.
  • name - The name of the IdP configuration - might be used as display name.
  • description - A description of the IdP.
  • subjectPoolKey - The subject pool key identifies the database where the end user is stored. Define any key - and use the same key if there is two Idp configurations that should use the same subject pool.
  • visibiltiy - Tells the degree of visibility of the IdP configuration. It can be:
    • PUBLIC - The IdP configuration is always visible
    • APPLICATION- Caller need to have valid Akkess token to read the IdP configuration
    • HIDDEN - The IdP configuration is hidden and can only be read using the Akkess Account token
  • adapter - The type of the IdP. It can be:
    • OIDC - OpenID Connect - adapterConfigOidc should be used
    • OAUTH_2 - OAuth 2.0 - adapterConfigOuath2 should be used
    • IAM_BASIC_IDP - Akkess Basic Idp - use for testing
  • adapterConfigOidc - The OIDC configuration for the IdP. The configuration is specific for the OIDC adapter.
    • issuer - The URL of the IdP
    • audience - The audience of the IdP. This is the client ID of the application
    • usernameMapping - The mapping of the username. The username is used to identify the actor in Akkess
      • attribute - The attribute in the IdP token that holds the username. Typically, 'email' or 'sub'
    • nameMapping - Optional. It common that user's name is part of the IdP token. Using nameMappingyou can configure Akkess to pick the user's name from the IdP token and store it into the user's Actor-object in Akkess.
      • attribute - The attribute in the IdP token that holds the name. Typically, 'name', 'firstName'
      • syncOption - The synchronization option. It can be:
        • NEVER - Never take the name from the IdP token
        • ONCE - The name is synchronized once when the actor is created
        • ALWAYS - The name is synchronized every time the actor logs in
  • adapterConfigOuath2 - The OAuth 2 configuration for the IdP. The configuration is specific for the OAUTH_2 adapter.
    • clientId - The public identifier for the application registered with the Identity Provider (IdP). It is used to identify the application during authentication and authorization.
    • clientSecret - A confidential key shared between the application and the IdP. It is used to authenticate the application and should be kept secure.
    • authorizeUrl - The URL of the IdP's authorization server where the user is redirected to grant consent and log in. This endpoint initiates the authorization flow.
    • tokenUrl - The URL of the IdP's token server where the application exchanges the authorization code for an access token. This endpoint is used to obtain tokens after the user has been authorized.
    • userInfoUrl - he URL of the IdP's endpoint for user information. This endpoint is used to retrieve information about the authenticated user.
    • subjectMapping - The mapping of the subject's identity. The subject is used to identify the actor in Akkess
      • attribute - The attribute in the IdP token that holds the subject identity. Typically, 'sub' or 'id'
    • usernameMapping - The mapping of the username. The username is used to identify the actor in Akkess
      • attribute - The attribute in the IdP token that holds the username. Typically, 'email' or 'username'
      • nameMapping - Optional. It common that user's name is part of the IdP token. Using nameMappingyou can configure Akkess to pick the user's name from the IdP token and store it into the user's Actor-object in Akkess.
        • attribute - The attribute in the IdP token that holds the name. Typically, 'name', 'firstName'
        • syncOption - The synchronization option. It can be:
          • NEVER - Never take the name from the IdP token
          • ONCE - The name is synchronized once when the actor is created
          • ALWAYS - The name is synchronized every time the actor logs in

Example:

const oidcConfig = {
  "adapter": "OIDC",
  "name": "Google",
  "description": "Used for sign in using Google account",
  "subjectPoolKey": "google",
  "visibility": "PUBLIC",
  "description": "Used for sign in using Google account",
  "adapterConfigOidc": {
    "issuer": "accounts.google.com",
    "audience": "xyz.apps.googleusercontent.com",
    "usernameMapping": {
      "attribute": "email"
    },
    "nameMapping": {
      "attribute": "name",
      "syncOption": "ONCE"
    }
  }
}

const oatuh2Config = {
  "adapter": "OAUTH_2",
  "name": "Google",
  "description": "Used for sign in using Google account",
  "subjectPoolKey": "google",
  "visibility": "PUBLIC",
  "description": "Used for sign in using Google account",
  "adapterConfigOauth2": {
    "clientId": "abc",
    "clientSecret": "xxx",
    "authorizeUrl": "https://accounts.google.com/o/oauth2/v2/auth",
    "tokenUrl": "https://oauth2.googleapis.com/token",
    "userInfoUrl": "https://openidconnect.googleapis.com/v1/userinfo",
    "usernameMapping": {
      "attribute": "email"
    },
    "nameMapping": {
      "attribute": "name",
      "syncOption": "ONCE"
    }
  }
}

Adapters​

The IdP configuration can be of different types. The type of the IdP configuration is defined by the adapter attribute. Based on chosen adapter the configuration will have different attributes that needs to be supplied.

Visibility​

When configuring an IdP you can choose if the IdP is public or private.

  • A public IdP is available for all callers. No token is needed. The application Id is supplied in the call.
  • An application private IdP is only available for callers with a valid Akkess token. The application Id is taken from the token.
  • A hidden IdP's configuration is not exposed via any API other than management APIs is only available for callers with.

Attribute mapping​

When a user is authenticated by an IdP, the IdP returns a token containing information about the user. The token is typically a JWT token. The token contains information about the user like email, name, picture etc.

The attributes subject, username and name can be mapped from the IdP token into the Akkess data model representing the user in Akkess.

Copyright © 2019 Akkess