Documentation

This guide outlines the configuration of SecureAuth IdP as an OpenID Connect Provider and OAuth 2.0 Authorization Server.

Supported OpenID Connect flows...
Authorization code
  • Obtains the authorization code from the authorization endpoint and all tokens are returned from the token endpoint
  • Returns an authorization code that can be exchanged for an identity token and / or access token
  • Requires client authentication using a client ID and secret to retrieve tokens from the back end
  • Permits long lived access through the use of refresh tokens

Implicit
  • Obtains all tokens from the authorization endpoint
  • Requests tokens without explicit client authentication
  • Uses the redirect URI to verify the client identity
  • Is not suitable for long lived access tokens; refresh tokens not supported
  •  'token', 'id_token', 'id_token token'

Supported OAuth 2.0 flows...
Authorization code
  • Obtains access tokens and refresh tokens
  • Optimized for server-side applications in which source code is not publicly exposed
  • Is a redirection-based flow; application interacts with the user-agent (user's web browser) and receives API authorization codes routed through the user-agent

Implicit
  • Obtains access tokens; refresh tokens not supported
  • Optimized for public clients operating a particular redirection URI; client secret confidentiality not guaranteed
  • Is a redirection-based flow; access token is given to the user-agent which passes it to the application (identity of the application is not authenticated)

Resource owner password credentials
  • Used as an authorization grant to obtain an access token; user provides service credentials (username and password) directly to the application for an access token
  • Eliminates the need for the client to store the resource owner credentials by exchanging credentials for a long-lived access token or refresh token
  • Should only be used on an application trusted by the user (user's desktop OS, or an application owned by the service)

Client credentials
  • Used as an authorization grant when the authorization scope is limited to protected resources under control of the client or the authorization server
  • Tokens are requested on behalf of a client, not a user, and requests are sent to the token endpoint

Supported endpoint types...
Authorization endpointResides on the authorization server on which the resource owner authenticates for access to the client application.https://.../secureauth1/secureauth.aspx
Token endpointResides on the authorization server on which the client application exchanges information for an access token. https://.../secureauth1/oidctoken.aspx
UserInfo endpointUsed to retrieve a user's identity information.https://.../secureauth1/oidcuserinfo.aspx



Prerequisites

  • SecureAuth IdP version 8.0 or later
  • Knowledge of OpenID Connect and OAuth 2.0.
  • Configure the Data tab in the SecureAuth IdP Web Admin with a directory integration



SecureAuth IdP configuration

  1. Once the directory integration is successful, go to the Data tab. 
  2. In the Profile Fields section, map the attributes from the profile fields to the SecureAuth IdP Profile Properties that will be used as OpenID Connect Claims. 
    The standard OpenID Connect Claims supported by SecureAuth IdP can be used as a reference.
  3. Save the configuration. 
  4. Go to the Post Authentication tab. 
  5. In the Post Authentication section, set the following: 

    Authenticated User RedirectSet to OpenID Connect/OAuth2


  6. In the OpenID Connect / OAuth 2.0 - Settings section, set the following: 

    EnabledSet security enhancement  to enable (True) or disable (False) OpenID Connect and OAuth2 endpoints. 
    IssuerSet the value used in the 'iss' claim.
    Signing CertCertificate used to sign JSON Web Tokens produced by SecureAuth IdP.
    Authorization Code Lifetime

    Length of time for Authorization Code lifetime in hours. 

    Access Token Lifetime

    Length of time for Access Token lifetime in hours. 

    The system is set with a default clock skew at 5 minutes (see https://docs.microsoft.com/en-us/dotnet/api/microsoft.identitymodel.tokens.tokenvalidationparameters.defaultclockskew?view=azure-dotnet).

    For example, if you set the Access Token Lifetime with a value of .25 for an intended token expiration at 15 minutes, it will actually expire at 20 minutes due to the default clock skew.

    Refresh Token LifetimeLength of time for Refresh Token lifetime in hours. 
    Consent Storage Attribute

    Data store attribute mapped to profile Property which saves the user's consent. 

    Sample image from Profile Fields section of the Data tab...

    For example, the Aux ID 10 field from the profile Property corresponds with the value set in the Consent Storage Attribute field. This field must be writable and support a varying character length. 

    The Consent Storage Attribute must be a Single-Value directory string attribute type (for example, houseIdentifier, adminDescription). 

    A single consent from the OIDC client starts at ~277 bytes, which means the attribute needs a minimum value of 1. 

    Each additional consent from an OIDC client increments by ~60 bytes.

    The maximum supported value for the attribute assigned to store the User Consent depends on how many OIDC clients your organization expects end users to connect to. 

    Example:
    "houseIdentifier" has a maximum value of 32768 bytes. so it could theoretically store 542 different consents.
    (32768 minus 277, then divided by 60 = 542)

  7. In the OpenID Connect / OAuth 2.0 - Scopes section, by default, a set of OpenID Connect scopes are preconfigured and required in certain OpenID Connect flows. To add a scope, click Add Scope and set the following: 

    ScopeValue passed to the endpoints during authorization requests. This value must be URL-safe and not include spaces. 
    Name

    User-friendly display name in list of scopes from which access is requested on the user consent page. 

    Description

    User-friendly description of scope in list of scopes from which access is requested on the user consent page.

  8. Save the configuration. 
  9. In the OpenID Connect / OAuth 2.0 - Clients section, click Add Client
  10. In OpenID Connect / OAuth 2.0 - Client Details, set the following:   

    EnabledSecurity enhancement to enable (True) or disable (False) the client. 
    Name

    User-friendly name of the client requesting access to display on the user consent page.

    Client IDAutomatically created unique identifier of the client.
    Client SecretAutomatically created unique secret of the client. 
    Authorization Code

    Indicate whether client can use the Authorization Code flow. 

    With the True setting, select the Use with PKCE Protocol check box to enable secure access to native and mobile apps using an Authorization Code flow with PKCE.

    Implicit

    Indicate whether client can use the Implicit flow.

    Client CredentialsIndicate whether client can use the Client Credentials flow.
    Resource OwnerIndicate whether client can use the Resource Owner flow.

  11. Save the configuration. 
  12. OPTIONAL. In the OpenID Connect / OAuth 2.0 - Client Scope Restrictions section, to restrict a client from using one or more of the defined Scopes, click Add Restricted Scope and add the Scope value.  
  13. OPTIONAL. In the OpenID Connect / OAuth 2.0 - Client Redirect URIs section, to let a client use the Authorization Code or Implicit flows, click Add Redirect URI and add the allowed URI value (must include https)
  14. Save your edits before leaving the Clients page
  15. In the Open ID Connect ID Token Claims section, do the following: 
    1. Map the Claim to the Profile Property. A value of Unmapped indicates the claim will not be included in the produced JSON Web Token. 
  16. In the Open ID Connect ID Token Custom Claims section, to create Custom Claims, click Add Custom Claim and set the following: 

    ClaimProvide unique name for the Custom Claim.
    Profile PropertySelect a Profile Property to complete the mapping. 

    SecureAuth supports creating Custom Claims to include in the 'id_token' for OpenID Connect flows.

    Claim names cannot include spaces.

  17. Save the configuration. 



Application X configuration steps

Use the Client ID and Client Secret from the SecureAuth IdP Web Admin to configure applications that are OpenID Connect / OAuth 2.0 ready.