5.14 OAuth and OpenID Connect

Access Manager Identity Server acts as an authorization server. It issues access tokens to a client application based on the user’s grant. A registered third-party client application uses API calls to retrieve the access token for accessing OAuth protected resources. For information about API calls, see the NetIQ Access Manager 5.0 Administration API Guide.

OpenID Connect implements a single sign-on protocol on top of the OAuth authorization process. It allows client applications to verify the identity of a user based on the authentication performed by Identity Server (authorization server). It also allows client applications to obtain a user’s basic profile information.

In this Section

5.14.1 How OAuth and OpenID Connect Helps

OAuth addresses the following concerns:

  • To provide access to protected resources, users share their credentials in clear text with third-party applications. Potential security breaches can result from the ability of third-party applications to store a user's credentials for future use.

  • The inability of resource owners to restrict a client application's access to protected resources for a specified duration or to limit the client application's access to a subset of resources.

  • The inability of resource owners to revoke a client application's access to a specific client application.

5.14.2 OAuth Keywords and Their Usage in Access Manager

Term

Explanation

Usage

Authorization Server

Access Manager Identity Server is the OAuth authorization server.

Identity Server issues OAuth tokens.

JSON Web Token (JWT)

The JWT token is signed as per JWS (JSON Web Signature) standard and encrypted as per JWE (JSON Web Encryption) standard by default.

Access token, refresh token, and ID tokens are in the JWT format.

Access Token

The token contains the attributes, such as scope, claims and duration specified in Access Manager for a resource server.

The access token can be consumed by resource server to validate the token by itself or by sending it to Access Manager. For more information, see Encrypting Access Token.

A client application can request for an access token by using API calls. For details about API requests and response, see NetIQ Access Manager 5.0 Administration API Guide.

Refresh Token

The client applications use this token to obtain a new Access token when the current Access token expires or is no longer valid.

This token can be revoked, which in turn invalidates Access token.

ID Token

This token contains a user’s claims such as identity, email address, and other profile information. This token is signed based on the algorithm that you specify during a client application configuration in Identity Server. It also specifies the issuing authority.

The client application can request for ID token to verify the identity of the user.

Client Key and Secret

The authorization server assigns a key and a secret to a client application while registering it.

The client applications can use the client key and secret to identify itself to the authorization server for retrieving the access tokens.

Resource Server

You can add a resource server in Identity Server to define the type of token that Identity Server can send for an OAuth request. For example, if you add a resource server in Identity Server with the details for encrypting the token using resource server keys, then based on the defined settings, Identity Server generates the token.

The client application can request for any scope defined in any of the Identity Server resource servers irrespective of the resource server name mentioned in the request. Identity Server will send the scopes in the token after the user authorizes it (for user attributes).

Scope

Scopes decide what resources client applications can access and what actions they can perform on the resources. It can include any user attribute from the user store or any custom claim.

Access Manager can issue only the defined scopes to the client application.

The required attributes or custom claims can be added to access token.

A user can authorize the client application to use the defined scopes.

Authorization Grants

Access Manager supports the following grants:

  • Authorization Code Grant

  • Implicit Grant

  • Resource Owner Credential Grant

  • Client Credential Grant

  • Security Assertion Markup Language (SAML) 2.0 Bearer Grant

The client application can use any of the available grants to request authorization.

5.14.3 Implementing OAuth in Access Manager

Access Manager uses variable length access tokens and authorization codes. Client applications and web servers must not assume any fixed size of tokens and codes, and must allocate necessary memory to handle the token. The token size depends on the size of scope names. Some servers have size limitations on query strings and HTTP headers. Ensure that an application uses only necessary scopes to avoid any issue.

Implementation flow of OAuth in Access Manager

  1. Develop a resource server (web application or REST service). (Application Developer)

  2. Identify scopes and permissions for this resource server. (Application Developer or Administrator)

  3. Add the resource server in Access Manager. See Adding a Resource Server. (Application Developer or Administrator)

  4. Define the identified scopes and permissions for the resource server in Access Manager. See Defining Scopes for a Resource Server. (Application Developer or Administrator)

  5. Develop a client application. (Client Application Developer)

  6. Register the client application in Access Manager. You can register a client by using Administration Console (Administrator), Identity Server (Client Application Developer or Administrator), or REST API (Client Application Developer or Administrator). For information about registering a client application on Administration Console, see Managing OAuth Client Applications.

  7. Identity Server assigns a unique client ID and client secret to this client application.

  8. Configure the client ID and secret in the client application. (Client Application Developer or Administrator)

  9. Deploy the resource server. (Application Developer)

  10. Deploy the client application. (Client Application Developer)

For information about scenarios where you can implement this configuration, see OAuth Scenarios.

For more information about how to enable and configure OAuth in Access Manager for this implementation flow, see Configuring OAuth and OpenID Connect.

5.14.4 OIDC Front-Channel Logout

Access Manager supports OIDC front-channel logout and is implemented as per OIDC specification. This feature enables the following two forms of logout request:

  • Identity Provider initiated logout request: Allows a user to log out from all the client applications when the user logs out at Identity Server.

  • Relying Party (client application) initiated logout request: When a user initiates logout from one client application, the user can authorize to log out from Identify Server and other logged-in applications. For more information, see OIDC RP-Initiated Logout.

Consider a scenario where multiple employees share a single device. A user named Alice logs in to the User Portal, and then accesses five client applications. At the end of her shift, she needs to log out of these applications so that Bob, another employee, can use the same device. Instead of logging out from each application individually, she can log out from the user portal. This logs her out from all five applications.

Alternatively, when she initiates logout from one client application, the client application initiates logout from Identity Server. Identity Server then triggers logout for the remaining four applications. A consent message is displayed to verify if she wants to log out from all applications. When she authorizes, she is logged out of Identify Server and the active applications.

The consent message is displayed when you enable the Require Logout Consent option in Global Settings. By default, this option is enabled. For more information, see Defining Global Settings.

To customize or localize a consent message, modify oauth2LogoutConsent.jsp using Advanced File Configurator.

The client application developer must register the logout_redirect_uri parameter for OIDC logout to enable this feature. The developer must also have the details of the following endpoints. Click Devices > Identity Servers > Edit > OAuth & OpenID Connect > EndPoint Summary to view the details of the endpoints.

  • Logout EndPoint

  • OpenID Metadata EndPoint

To configure the front-channel logout option, see Step 5 of Managing OAuth Client Applications.

To enable logout from multiple browsers, you must enable the Allow multiple browser session logout option under Devices > Identity Servers > Edit > General > Configuration > Limits.

You can also revoke refresh tokens issued during the front-channel logout for the user session using the Logout to revoke tokens option. By default, this option is disabled. For more information, see Defining Global Settings.

Figure 5-18 Identity Provider Initiated Logout Request

  1. A user initiates logout at the Identity Server User portal.

  2. The user agent sends the logout request to Identity Server.

  3. Identity Server returns the logout response. The response contains iframes (logout URLs) for each relying party (RP1, RP2, and RP3). The relying party can be OAuth 2.0 or OIDC client application or SAML2 client application.

  4. The browser agent generates responses and makes calls to each relying party’s logout URL.

Figure 5-19 Workflow of a Relying Party (client application) Initiated Logout Request

  1. A user initiates logout at the client application.

  2. The user agent sends the logout request to the client application.

  3. The client application redirects the user’s browser agent for Identity Server logout.

  4. The browser agent sends the logout request to Identity Server.

  5. After the user grants consent, Identity Server terminates the user session, sends logout requests to other client applications (OAuth 2.0 or OIDC client application or SAML2 client application), and optionally redirects to the client application’s post-logout page.

Request Parameters

You can include the following parameters in the query string of a request:

Parameter

Description

Type

Required

id_token_hint

A valid ID token issued for the user by Identity Server.

String

No

post_logout_redirect_uri

The redirect URI where the user is redirected after Identity Server logs the user out. This URI must match with the value provided during client registration. The id_token_hint parameter is required to redirect the user to this URI. If the logout request is sent without the id_token_hint parameter, the user is not redirected to post_logout_redirect_uri.

String

No

state

An optional value. This value is returned as a query parameter when the user is redirected to post_logout_redirect_uri.

String

No

NOTE:

  • When a user session expires or does not exist in Identity Server, and the logout request does not contain the post_logout_redirect_uri parameter, the user is redirected to the Identity Provider's login page.

  • When a user session expires and a registered post_logout_redirect_uri parameter is specified in the logout request, the user is redirected to the configured post-logout page.

  • The logout request contains the id_token_hint parameter with a valid value, and the subject matches the current user session. However, the token is expired. The user session is then logged out at Identity Server and it redirects the user's browser agent to the configured post-logout page.

Sample Request 1

The client application initiates a logout without the post_logout_redirect_uri parameter. After logout, the user is redirected to the Access Manager's login page. The end_session endpoint supports both HTTP GET and POST methods.

GET/POST https://<idpcluster>:<port>/nidp/oauth/v1/nam/end_session

Sample Request 2

The client application initiates a logout. After logout, the user is redirected to the registered post_logout_redirect_uri.

GET https://<idpcluster>:<port>/nidp/oauth/v1/nam/end_session?
  id_token_hint=${id_token}&
  post_logout_redirect_uri=${post_logout_redirect_uri}&
  state=${state}

For example:

GET https://<idpcluster>:<port>/nidp/oauth/v1/nam/end_session?
  id_token_hint=eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiw…..&
  post_logout_redirect_uri=https://client.example.org/logoutRedirect&
  state=JaysvoMyK71YfVG5

Sample Response

HTTP 302 Found
Location: https://{post_logout_redirect_uri}&state=${state}

For example:

HTTP 302 Found
Location: The user will be redirect to the URI https://client.example.org/logoutRequest&state= JaysvoMyK71YfVG5

Error Conditions

  • If the id_token_hint parameter contains either invalid or encrypted ID Token, a 401 HTTP error response is returned with the Invalid ID Token error message.

  • If the post_logout_redirect_uri parameter value does not match with the registered client application, a 401 error response is generated.

5.14.5 Configuring OAuth and OpenID Connect

NOTE:Technical Support Team supports the Access Manager setup and any app issues where the API request is sent to the correct Access Manager endpoint. Any other code changes that are needed to integrate with Access Manager are outside the scope of traditional support and need to go through the namsdk@microfocus.com channel.

The following is the sequence of the OAuth and OpenID Connect configuration:

  1. Enable the OAuth protocol in Administration Console

  2. Define the global settings

  3. Configure a resource server

  4. Configure scopes (user attributes and claims) for a resource server

  5. Register client applications

NOTE:Use Internet Explorer 10 or later, Firefox, or Chrome for configuring OAuth 2.0.

Enabling OAuth and OpenID Connect

To use OAuth, you must enable it in Identity Server. Otherwise, the configuration will not work.

  1. Click Devices > Identity Servers > Edit.

  2. In the Enabled Protocols section, select OAuth & OpenID Connect.

  3. Click OK and update Identity Server.

NOTE:For OAuth authorization, Identity Server, and ESP must be enabled with SSL.

Extending a User Store for OAuth 2.0 Authorization Grant Information

Access Manager OAuth 2.0 implementation stores the client application information, which a user authorizes to access attributes and resources. This information is unique per user. Store it as part of a user object in the user store. If you already have an attribute, use it in Authorization Grant LDAP Attribute while defining Global Settings.

If a free attribute is unavailable, then extend the User Object schema to add a new single-valued binary (LDAP) or stream (eDirectory) attribute with a name. Access Manager stores an XML object in this attribute for each user authorization.

NOTE:The LDAP super administrator must have write access to this user attribute to allow saving the token information. Access Manager uses this attribute to revoke refresh tokens.

An example for extending the schema of a User Object in eDirectory

  1. Click to Roles and Tasks > Schema > Create Attribute.

  2. Specify Attribute Name as nidsOAuthGrant.

  3. Click Next.

  4. Select Stream under Syntax.

  5. Click Next.

  6. Select Single Valued.

  7. Click Next > Finish.

  8. Go to Roles and Tasks > Schema > Add Attribute.

  9. Select Person under Available Classes.

  10. Click OK.

  11. Move nidsOAuthGrant from Available optional attributes to Optional attributes.

  12. Click OK.

An example for extending the schema of a user object in Active Directory

  1. In Windows, Start > Run > mmc.

  2. Click File > Add/Remove Snap-in.

  3. Select Active Directory Schema and click Add.

  4. Expand Active Directory schema, then right click Attributes > Create Attribute.

  5. In Create New Attribute, specify the following:

    • Common Name: nidsOAuthGrant

    • LDAP Name: nidsOAuthGrant

    • Unique X500 Object ID: 1.3.6.1.4.1.1466.115.121.1.5

  6. Select Syntax as Octet string. Ensure that Multi-Valued is deselected.

  7. Click OK.

  8. Expand Active Directory schema, then click Classes > person.

  9. Right click person, then click Properties.

  10. Click the Attribute tab, then click Add.

  11. Select the attribute that you created (nidsOAuthGrant), then click OK.

  12. Click OK to close all property windows, then add the attribute to person class.

Sample: Extending the schema of a user object in Active Directory Lightweight Directory Services

  1. Go to Active Directory Lightweight Directory Services (AD LDS) schema.

  2. Right-click the schema name, then click New > Object.

  3. Select attributeSchema and click Next.

  4. Specify a common-name and click Next.

  5. Specify 4 for the oMSyntax attribute and click Next.

  6. Specify a LDAP-Display-Name and click Next. This value must be same as the common-name.

  7. Specify True for the isSingleValued attribute and click Next.

  8. Specify 2.5.5.10 for the attributeSyntax attribute and click Next.

  9. Specify 1.2.840.113556.1.9000.50.1 for the attributeID attribute and click Next.

  10. Click Finish.

  11. Navigate to cn=Person class, double-click to edit an attribute.

  12. Select mayContain attribute and click Edit.

  13. Specify the attribute name (common-name) and click Add > OK > Apply > OK.

  14. Right-click the Schema > Update Schema Now.

    NOTE:While creating a new user, the msDS-UserAccountDisabled attribute is set to true by default. Change the value to false.

Defining Global Settings

The Global Settings enable you to specify the default OAuth and OpenID Connect settings for the authorization server, such as issuer URL, token types, and grants.

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Global Settings.

  2. The following options are available:

    Field

    Description

    Issuer

    Specify the name of the authorization server. This name is part of the ID token.

    Authorization Grant LDAP Attribute

    Specify a binary or a stream (for eDirectory) attribute that exists in the user store. For example, nidsOAuthGrant.

    The super administrator must have the write access to the specified Authorization Grant LDAP Attribute. This attribute stores user consent and the refresh token information. This attribute gets updated when Identity Server performs the following actions:

    • Issues a refresh token

    • Revokes the issued refresh token

    • Include user consent information

    For information about creating the attribute in the user store, see Extending a User Store for OAuth 2.0 Authorization Grant Information.

    NOTE:This is a mandatory field. This attribute stores the refresh token information. This information can be used later for a JWT token to check for revocation. Ensure that no other application uses this attribute.

    CORS Domains

    Select any one of the following options based on the requirement:

    • None: To deny access for requests from all domains other than the domain of the resource. The resource referred here are resources such as Javascript on the client application.

    • Allow All: To allow access for requests from any domains.

    • Limit to: To allow access for requests from only selected domains. Specify the domain with the port number. Do not specify the port if you are using port 80 or 443.

    Examples: beem://www.test.com:port, fb://app.local.url:port, https://namapp.com:port

    NOTE:Access Manager provides an access token even when the request does not include the listed domain. But, the token is validated on the following endpoints:

    • UserInfo

    • TokenInfo

    • Revocation

    • Token Introspect

    This invalidates the access token if the request comes from a different domain.

    Access-Control-Allow-Credentials Header

    Select this option to allow the Access Manager CORS filter to send the Access-Control-Allow-Credentials header with the response.

    Grant Type(s)

    Select the types of grants that the authorization server will support. Based on the grant type you select, the system selects corresponding token type by default.

    For more information about grant types, see OAuth Authorization Grant.

    Token Type(s)

    Select the types of tokens that the authorization server will support.

    • ID Token: A security token that contains claims about the authentication of an end user by an authorization server to the relying party.

    • Access Token: Includes the specific scopes and durations of granted access.

    • Refresh Token: Obtains a new access token when an Access token becomes invalid or expires.

    Require Logout Consent

    Use this option when you have configured OIDC front-channel logout for client applications. Enabling this option displays a consent message to users seeking their permission to log out from all logged-in applications. For more information, see OIDC Front-Channel Logout.

    By default, this option is enabled.

    Enable Token Revocation

    Enable this option to revoke the refresh token.

    If you do not require to revoke the refresh token, you can disable this option. When you disable this option the token information does not get saved in the authorization grant LDAP attribute.

    To revoke a refresh token, the super administrator must have the write access to the specified Authorization Grant LDAP Attribute. If you do not want to use this attribute or do not have the write access to this attribute, you must not select this option.

    NOTE:Revocation of binary tokens is not supported.

    Perform Revocation Check After

    Specify the duration in seconds. After this duration, Access Manager verifies whether the token is revoked.

    Use this option if you have configured a user store as an LDAP load balancer, which has a read-only and write-only replica. The Authorization Server reads the user attributes in LDAP for token verification. However, the token verification fails if any delay occurs in data synchronization across the user store LDAP replicas.

    Using this option, you can delay the token verification for a specific time. During this delay period, the Authorization Server will not read the user attribute in LDAP for token verification. However, it will verify other required checks.

    Logout to revoke tokens

    Select this option to revoke the refresh tokens during logout. By default, this option is disabled.

    Authorization Code Timeout

    Specify the duration in minutes after that the authorization code becomes invalid.

    Access Token and ID Token Timeout

    Specify the duration in minute after how long the Access token and ID token become invalid.

    Refresh Token Timeout

    Specify the duration in minute after how long the Refresh token becomes invalid.

    Signing Certificate

    Select a signing certificate to sign the tokens. By default test-signing certificate is assigned with hashing algorithm details. The signing keys can be retrieved from JSON Web Key Set endpoint.

    To add the external OAuth signing certificates in the certificate list, ensure that you have added the certificate in the Signing keystore of the Identity Server.

    Contracts for Resource Owner Credentials Authentication

    Select the contracts in Available contracts and move them to Contracts.

    This option allows the administrator to configure the Resource Owner flow to execute specific authentication contract.

    The order of authentication contract execution must be as follows:

    1. The acr_values in request parameter

    2. OAuth Global Setting option

    3. Default contract

    For example, if no acr_values and no global RO authentication contracts are specified, then only the default authentication contract of Identity Server is executed.

    To select a custom contract for authentication, the custom authentication class must override the cbAuthenticate method. For more information, see the Access Manager 5.0 SDK Guide.

    To configure the contract as a second-factor authentication contract, see Configuring Multi-Factor Authentication for Resource Owner Credentials Grant.

  3. Click OK.

Configuring a Resource Server

You can define settings for encrypting access tokens by adding a resource server in Identity Server. You can add a resource server based on the encryption requirement of each OAuth resource server. A resource server validates and accepts tokens sent by client applications and grant access to resources.

You can select any resource server as the default resource server. Then the tokens are issued and encrypted using the default resource server keys. If you do not select any resource server as the default resource server, then Identity Server is considered as the default resource server.

You can also modify and delete configured resource servers. Configuring a resource server consists of the following actions:

Adding a Resource Server

Adding a resource server in Access Manager (Identity Server) is required only for specifying any of the following access token encryption mechanism for a specific OAuth resource server:

  • Encrypt using Access Manager key (default)

  • Encrypt using resource server key

  • No encryption

Access and ID tokens contains scopes (user’s claims) in the form of user attributes or permissions for the clients to use the protected resource. You can configure scopes for each resource server.

When a client application requests for a token with specific scopes and the user provides the consent, Identity Server (authorization server) checks if the scope is available in any of the added resource servers. If available, the scope is added to the access token irrespective of the name of the resource server specified in the request.

Scenario 1

An administrator adds resource servers RS1 and RS2 based on the access token encryption requirement of the corresponding OAuth resource servers.

The administrator configures RS1 to use Access Manager key for encrypting access token and configures RS2 to use the resource server's key. In addition, the administrator defines the scope, Scope1 for resource server RS1 and the scope, Scope2 for resource server RS2.

Resource Server

Encryption mechanism

Scopes

RS1

Encrypt using Access Manager key

Scope1

RS2

Encrypt using resource server key

Scope2

When the client application sends a token request with scope parameter as Scope1 and resourceServer parameter as RS2, Identity Server adds Scope1 to the token with the encryption mechanism specified in RS2.

Request

Response

Parameter

Value

Scope added to token

Token encryption mechanism

resourceServer

RS2

Scope1

Encrypted using resource server, RS2 key

scope

Scope1

Scenario 2

The administrator selects RS1 as the default resource server, and configures both RS1 and RS2 to use the resource server's key to encrypt access token. The resourceServer parameter is not defined.

Resource Server

Encryption mechanism

Scopes

RS1 (default)

Encrypt using resource server key

Scope1

RS2

Encrypt using resource server key

Scope2

When the client application sends a token request, Identity Server adds Scope1 to the token with the encryption mechanism specified in RS1.

Request

Response

Parameter

Value

Scope added to token

Token encryption mechanism

scope

Scope1

Scope1

Encrypted using resource server, RS1 key

IMPORTANT:Be careful if you change the default resource sever because certain requests can fail.

For example, if you change the default resource server from RS1 to RS2, the token will be issued and encrypted using RS2 keys. Then, if a client application sends a token encrypted by RS1 keys, the token request will fail because RS1 is not the default resource server.

If you delete the default resource server, and Identity Provider is available, it becomes the default resource server. If Identity Provider is not available, the tokens are encrypted using the Access Manager keys.

When Identity Provider is the default resource server, you cannot delete it or modify the name. You can set only one resource server as the default one at a time.

Scenario 3

The administrator selects RS2 as the default resource server, and configures both RS1 and RS2 to use the resource server's key to encrypt access token.

Resource Server

Encryption mechanism

Scopes

RS1

Encrypt using resource server key

Scope1

RS2 (default)

Encrypt using resource server key

Scope2

Now, when the client application sends a token request with scope parameter as Scope1 and resourceServer parameter as RS1, Identity Server adds Scope1 to the token with the encryption mechanism specified in RS1. When defined, the resourceServer parameter is given priority over the default resource server setting.

Request

Response

Parameter

Value

Scope added to token

Token encryption mechanism

resourceServer

RS1

Scope1

Encrypted using resource server, RS1 key

scope

Scope1

Perform the following steps to add a resource server in Identity Server:

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Servers > New.

  2. Specify a name for the resource server.

  3. (Optional) Select Set it as the default Resource Server. When you enable this option, tokens are issued and encrypted using the default resource server keys

  4. Select the appropriate encryption method for encrypting access token. For more information about encrypting an access token, see Encrypting Access Token.

    • Do not encrypt: Select this option if you do not require encryption of Access token.

    • Encrypt using Access Manager Key: This is the default option. If you select this option, the token is encrypted and validated by using Access Manager Keys.

    • Encrypt using Resource Server Key: This option is used for encrypting a token by using encryption algorithm and keys that the resource server can use for decrypting the token.

  5. (Conditional) If you select Encrypt using Resource Server Key, specify the following details:

    For information about fields, see Encrypting the Token with the Resource server Key.

    • Resource Server Encryption Keys: Specify the resource server’s JWKS. You can also specify a valid URL where the resource server keys are defined.

    • Key Encryption Algorithm: Specify the algorithm that should be used for encrypting the key of the encrypted token by using the resource server’s public key.

      Ensure that this algorithm can be used by one of the public keys in the resource server’s JWKS or the URL.

      NOTE:If the specified key encryption algorithm does not match with the value of the algorithm in Resource Server Encryption Keys, Access Manager fails to send the token.

    • Token Encryption Algorithm: Specify an algorithm available in the resource server’s JWKS for generating random symmetric key to encrypt the access token.

    Following is an example of JSON Web Key set that can be used when Key Encryption Algorithm is selected as A128KW and the Token Encryption Algorithm is selected as A128CBC-HS256(Default):

    {
    "keys": [
        {
            "kty": "oct",
            "use": "enc",
            "kid": "i8X0RShbVxrBEG1-ests_Zx_PE7XYvc3iBTIaTAS_5A",
            "k": "Vlbwxl5hbCOLMwupPc2hDw",
            "alg": "A128KW"
        }
    ]
}

    NOTE:You cannot configure resource server with JWKS containing kid value between 0-10 as it is used by Access Manager keys.

  6. Click Next.

    Continue with Defining Scopes for a Resource Server.

IMPORTANT:Before deleting a resource server, ensure that it is not used in any OAuth token inject policy.

Restricting the Number of Requests

You can restrict the number of users accessing a service by updating the tomcat.conf file.

Open Identity Server’s tomcat.conf and add the following parameter:

JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.oauth.threshold.maxrequestsallowed=<number of requests>"

For example, JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.oauth.threshold.maxrequestsallowed=10". It will not allow more than 10 requests per second.

For information about how to open and modify a file, see Modifying Configurations.

Defining Scopes for a Resource Server

A scope is a set of permissible actions that a client application can perform on the accessed resources. You can define scopes by providing user claims, such as user attributes and permissions. The client application developer can request for required scopes, which an administrator uses for configuring the resource server in Identity Server (authorization server). However, there is no restriction for any client application to use any of the scopes configured in any resource server. For more information, see Adding a Resource Server. It is recommended to select Require user permission to get consent from the user whenever the scope contains user attributes.

When a user grants client applications access to protected resources, they can perform actions based on permissions defined in the scope.

For example, if you have defined a scope named email and defined permissions associated with this scope, such as read only. A client application that will access the email can only read the content.

NOTE:

  • You can get LDAP-based attributes in a scope.

  • You can configure roles as an OAuth scope and use them to inject with the Identity Injection policy. The role attribute is calculated when a token is sent to UserInfo Endpoint.

  • If you have registered a client application to use binary token, you cannot add user attributes and claims to the token.

Perform the following steps to define scopes and permissions:

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server.

  2. Select the resource server name for which you want to define a new scope.

  3. Click New and specify the following details:

    Field

    Description

    Name

    Specify a name for the scope.

    Description

    Specify a description for the scope. The consent page shows this description.

    Include claims of type

    Select the type of user’s claim to be used in the scope. You can select any of the following types:

    • User Attributes: Select this option if you require using any of the user’s LDAP attributes in the scope. You can also use virtual attributes in the scope.

      NOTE:

      • You can use virtual attributes for LDAP-based attributes and constant values.

      • This option does not work in a client credentials flow.

    • Custom Claims/Permissions: Select this option if you want to restrict specific permissions for this scope. This option is useful when a client application requires specific permission, such as read, write and so on to access a resource.

      For example, when you configure a read permission for the scope, the client application can request for this scope and get the token.

    Require user permission

    Select this option if this scope requires user’s consent before providing access to the protected resources. It is recommended to keep this option selected when user attribute is used in the scope.

    In a client credentials flow, the token does not include scopes that require user permissions. Therefore, deselect this option. When the option is deselected, the claims can be fetched from the UserInfo Endpoint.

    • When this option is enabled and the prompt=consent parameter is sent in the authorization endpoint, the user consent screen is displayed.

    • When this option is enabled, and the prompt=none parameter is passed in the authorization endpoint, the user consent screen is not displayed.

    • When this option is disabled, and the prompt=none parameter is passed in the authorization endpoint, the user consent screen is not displayed.

    • When this option is disabled, and the prompt=consent parameter is passed in the authorization endpoint, the user consent screen is not displayed.

    NOTE:If you deselect this option, the scope is not listed in the scopes_supported field of the metadata endpoint. The claims_supported field of the metadata endpoint does not display the claims for this scope even if the user attribute or the custom claims/permissions are configured.

    Allow modification in consent

    Select this option to allow modification in consent. When selected, the resource owner can choose not to share the scope with the client application.

    The consent page will display a check box against each scope to choose the scopes that can be shared with the client applications.

  4. Click Next and continue with Configuring User Claims or Permission in Scope.

Configuring User Claims or Permission in Scope

You can include user’s attributes or a client application’s claim in the scope.

  1. (Conditional) If you chose User attributes to create scope, perform the following steps:

    1. Select the required attribute set from the LDAP profile or create a new attribute set.

      This lists the user attributes in the attribute set.

      NOTE:You can add any configured LDAP based virtual attribute to the scope of the access token. You can add a virtual attribute by creating an attribute set that includes the virtual attributes. For information about creating an attribute set, see Configuring Attribute Sets.

    2. To add the user attribute scope to the access token, select the required attributes that should be added to the access token, then click Add > Add to Access Token.

      If you want to remove a specific attribute from the access token, click Remove > Remove from Access Token. When you remove the attribute from the access token, the attributes will not be removed from the already issued token.

    3. To add the user attribute scope to the ID token, select the required attributes that should be added to the ID token, then select Add > Add to ID Token.

      NOTE:The token size varies based on the attribute value that is included in the token. Hence, it is recommended to include only the required attribute to the token.

      If you require to remove a specific attribute from the ID token, select the attribute then click Remove > Remove from ID Token.

      NOTE:The attributes are not added to or removed from an issued ID token.

    4. (Conditional) If you require the selected attributes to be available in both ID token and access token, then after selecting the attributes click Add > Add to Both.

      If you require to remove specific attributes from both access token and ID token, then after selecting those attributes click Remove > Remove from Both.

  2. (Conditional) If you have used Custom Claims/Permissions, perform the following:

    1. Click New to create a new custom claim.

    2. In Add claim/permission, specify the permission that the client is allowed after consuming the access token.

    3. Select the required claim that to be added to the access token, then select Add > Add to Access Token.

      To remove a specific claim from an access token, click Remove > Remove from Access Token.

      NOTE:The claims are not added to or removed from an already issued access token. You can view the new Claims/Permissions in the claims set. The key name is claims and the value is a list of strings.

    4. Select the required claim to be added to the ID token, then select Add > Add to ID Token.

      To remove a specific claim from the ID token, click Remove > Remove from ID Token.

      NOTE:Claims are not added to or removed from an issued ID token. You can view the new Claims/Permissions in the claims set. The key name is claims and the value is a list of strings.

    5. (Conditional) If you require to select the claims that must be available for both access token and ID token, then after selecting the claims click Add > Add to Both.

      To remove claims from both tokens, select claims, and click Remove > Remove from Both.

      NOTE:The claims are not added to or removed from the already issued tokens. These claims are displayed as list of strings under the claims attribute in access and ID tokens.

Managing Scopes of a Resource Server

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server.

  2. Click the resource server > scope you want to modify.

  3. On the Edit Scope page, modify the details as required. For information, see Defining Scopes for a Resource Server.

  4. Click OK.

Modifying Claims and Attributes

You can modify or delete a defined claim. You can also update the attributes associated with a scope. If you have selected Require user permission while creating the scope, Identity Server fetches the required information from the userinfo endpoint. You can change the associated LDAP attributes.

To delete a custom claim or permission, you can select the required permission and click Delete.

For information about user attributes and claims, see Defining Scopes for a Resource Server.

Managing OAuth Client Applications

A client application that sends API requests to Access Manager must be registered with Access Manager Identity Server. You can register a client application by using the API calls, Administration Console, or the Identity Server user portal page.

Prerequisites for managing client applications include:

  • User Portal: Define any of the following roles in the OAuth policy for the user:

    • NAM_OAUTH2_DEVELOPER: Allows the user to view and modify the client registration details of the applications that the user has registered on the portal.

    • NAM_OAUTH2_ADMIN: Allows the user to view and modify the client registration details of all the client applications that are registered with Access Manager.

    The user (an application developer) must log in to Identity Server for registering a client application. The My Applications tab lists all applications that the user has added. The user can view details, modify, and delete applications.

  • API calls: Define the NAM_OAUTH2_ADMIN role in the OAuth policy for the user.

  • Administration Console: The user must request the Access Manager administrator to register a client application using Administration Console.

Registering OAuth Client Applications

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Client Applications > Register New Client.

  2. In Client Configuration, select Enable Client and specify the following details:

    Field

    Description

    Client Name

    Specify the name of the client application.

    Client Type

    Select whether this is a web-based or a desktop client application.

    If you select Native/Desktop, Use Persistent Cookie gets displayed.

    You can select Use Persistent Cookie to allow single sign-on for a user who uses client applications on a desktop or a mobile.

    For example, a user accesses client A using the credentials and gets authenticated. Client A receives a refresh token and an access token. Now, user accesses client B immediately or after few days. If Use Persistent Cookie is enabled for client B, then the client uses the persistent cookie to retrieve the token and authenticate the user. Hence, client B will get authenticated automatically.

    If Use Persistent Cookie is not selected for client B configuration, user has to provide credentials to retrieve refresh token and access token.

    NOTE:When a client application uses the Authorization Code flow, the request must contain the revocation_id parameter along with the clientID parameter. The revocation_id value can be the device ID.

    If revocation_id is not included in the request, the user cannot use the persistent cookie to authenticate from client B.

    Login Redirect URIs

    Specify the URI based on the Client type.

    Specify the URIs that Identity Server uses to send the authorization code and implicit requests.

    For web-based applications, specify the client type in this format: https://client.example.org/callback

    For native/desktop applications, specify the client type in any one of the following formats:

    https://www.namnetiq.in/

    x-com.netiq.sample://www.namnetiq.in/

    urn:ietf:wg:oauth:2.0:oob (supported only for the authorization code flow).

    NOTE:The limitation on the attribute in the eDirectory (Octet string) is 64K of data.

    Grants Required

    Select the grant types required for this client application. Available grant types include:

    • Authorization Code (default)

    • Implicit

    • Resource Owner Credentials

    • Client Credentials

    • SAML 2.0 Assertion

    Token Types

    Select the type of tokens that the authorization server will send to this client application:

    • Code

    • ID Token

    • Refresh Token

    • Access Token

    Refresh Token

    Select Always Issue New Token to issue a new refresh token for each refresh token request.

  3. (Conditional) If you selected ID Token in Client Configuration > Token Types, click OpenID Connect Configuration, and configure the following settings:

    Field

    Description

    JSON Web Key Set URI

    To encrypt an ID token using the public key of a client application, specify the client’s JSON Web Key Set URI. This is required to retrieve the encryption key that are defined in the JSON Web Key Set URI.

    ID Token Signed Response Algorithm

    This is a mandatory field for issuing an ID token to a client application. If you require Identity Server to sign the ID token using a JWS algorithm, select the appropriate signing algorithm. The signing algorithm depends on the certificate that is specified under Certificate Settings in the Global Settings page.

    For example, if Signing Algorithm is RS256 on the Global Settings page, select RS256.

    NOTE:If you select None, the ID token is sent as an unsigned token. Ensure to select this option only if you trust the integrity of an unsigned ID token.

    ID Token Encrypted Response Algorithm

    Specify the JWE algorithm to encrypt the key of the encrypted content in the ID token.

    NOTE:Ensure to specify the algorithm that is defined in the specified JSON Web Key Set URI so that the client application can use the private key to decrypt the token.

    ID Token Encrypted Response Enc

    This field gets auto-populated based on the algorithm specified in ID Token Encrypted Response Algorithm. JWE enc algorithm is required to encrypt the content of the ID token.

  4. Click Token Configuration. The timeout settings here overrides the global settings.

    Field

    Description

    Authorization Code Timeout

    Specify the duration after which the authorization code will expire.

    Access Token and ID Token Timeout

    Specify the duration after which access and ID tokens will expire.

    Refresh Token Timeout

    Specify the duration after which the refresh token will expire.

    Access Token and Refresh Token Format

    It is recommended to select the JWT token. However, you can select any of the following options:

      • Default: The format is set to binary or JWT based on the value you set in the OAUTH TOKENS IN BINARY FORMAT property of Identity Server.

        If OAUTH TOKENS IN BINARY FORMAT is

        • set to true, the format is binary.

        • set to false, the format is JWT.

        • unspecified, the format is JWT.

        When you update the value or add OAUTH TOKENS IN BINARY FORMAT, any client application with the Default option receives the tokens (access and refresh) in the modified format.

      • Binary: The token format is always binary irrespective of the value set in the OAUTH TOKENS IN BINARY FORMAT property of Identity Server.

        Binary tokens are always encrypted using Access Manager keys. To validate a token, the resource server uses Access Manager UserInfo and TokenInfo endpoints.

        If tokens are in the binary format, the following features are unavailable:

        • Encrypting an access token using the resource server key

        • Revoking a refresh token

        The Binary option is recommended only if you have an existing client application that cannot use JWT because some browsers restrict the length of the parameter values.

      • JWT: Recommended option. The token format is always JWT irrespective of the value set in the OAUTH TOKENS IN BINARY FORMAT property of Identity Server.

  5. Click Logout Configuration and specify the following details:

    Field

    Description

    Front-Channel Logout URI

    Specify the client application logout URL that Identity Server will use to trigger logout at the client application

    Enable Session Token

    When you enable this option, Identity Server includes session ID and issuer query parameters in the client application’s logout URL.

    This session ID is a co-relation ID that the client application uses to identify the unique user sessions established at Identity Server. It is not the Identity Server user session ID.

    Logout Redirect URIs

    (Applicable only for the Relying Party initiated logout request)

    Specify the URL to which the user will be redirected after logout. For example, https://client.example.org/logout.

    NOTE:The logout request (end_session) must include id_token_hint and post_logout_redirect_uri request parameters. Else, Identity Server does not redirect the user to the post-logout page.

    For information about the OIDC front-channel logout support, see OIDC Front-Channel Logout.

  6. Click Consent Screen Configuration and specify the following details:

    Field

    Description

    Client Logo URL

    Specify the URL of the logo that you want to include on the consent page.

    Privacy Policy URL

    Specify the URL of the privacy policy you want to include on the consent page. You can define your own privacy policy.

    Terms of Service URL

    Specify the URL of the terms of service.

    Contacts

    Specify the email addresses of people related to this client application.

  7. Click Authorized JavaScript origins (CORS) and add Domains. Domains configured here can access restricted resources available on the client application. Do not specify the port if you are using port 80 or 443.

    For example, beem://www.test.com:port, fb://app.local.url:port, https://namapp.com:port

  8. Click Authentication Contract to configure authentication contracts for the client application. This configuration is available in Access Manager 5.0 Service Pack 1 and later.

    When you configure authentication contracts for a client application using here, this server-side configuration takes precedence. After this configuration, the ACR value in the request is ignored, and contracts are used for authentication.

    In Available Contract, select contracts that you want to be used for authentication and move these to Satisfy Contract. By default, the first contract in the list is used. For the Resource Owner Credentials flow, if the identity provider does not support that contract, then the next contract in the list is used for authentication.

  9. Click Scope Configuration and select the required scopes for the client application.

    Field

    Description

    Scopes

    Select scopes that the client application can use.The client application can use only the scopes specified here. If the client application sends a non-configured scope, it will not be considered.

  10. Click Register Client.

    Identity Server assigns a client ID and a client secret. To see this ID and secret, go to the Client Application page and click the view icon for this client application.

Modifying Registered Client Applications

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Client Applications.

    The page lists all registered client applications along with the following details:

    Field

    Description

    Client Application

    Name of the registered application

    Application Type

    Type of the application: Web or Native/Desktop

    Created By

    User name of the person who has registered the client application.

    Actions

    List of icons associated with actions that you can perform on an application. You can perform the following actions:

    • View details of a registered client application

    • Modify details of a registered client application

    • Delete a registered client application

    • Disable a client application.

      Disabling a client application does not delete it, and it will not revoke any token issued earlier. When you enable the client application again, the token issued earlier does not expire and will continue to work.

  2. Click the edit icon under Actions. Modify the details as required. For information about fields, see Registering OAuth Client Applications.

  3. Click Modify Client.

5.14.6 Using Access Gateway in the OAuth Flow

The following diagram depicts the OAuth flow when using Access Gateway for protecting the APIs, injecting scopes, and retrieving the access token:

OAuth Implementation using Access Gateway

  1. Determine the web application or REST service for which you want to implement this configuration.

  2. Create a reverse proxy in Access Gateway and enable OAuth in Access Gateway for this reverse proxy. See Enabling OAuth in Access Gateway.

  3. Configure an authorization policy based on OAuth Scopes. See Configuring an Authorization Policy based on OAuth Scopes.

  4. Configure an Identity Injection policy to inject user name and password. See Configuring an Identity Injection Policy for OAuth Claims.

  5. Configure optional Identity Injection policies to inject other user claims, if required. You can define the additional roles in the same policy also that you configured for injecting user name and password. See Configuring an Identity Injection Policy for OAuth Claims.

  6. Apply the changes.

For information about how to configure OAuth in Access Manager for this implementation flow, see Configuring Access Gateway for OAuth.

5.14.7 Configuring Access Gateway for OAuth

You can configure Access Gateway to validate OAuth tokens on behalf of the resource server. If the token is not valid then Access Gateway returns the unauthorized 401 error to the client application. You can also configure Access Gateway to inject OAuth tokens on behalf of the web applications.

Configuring Access Gateway for OAuth consists of the following steps:

  1. Enabling OAuth in Access Gateway

  2. Configuring an Authorization Policy based on OAuth Scopes

  3. Configuring an Identity Injection Policy for OAuth Claims or Configuring an Identity Injection Policy for User Passwords

  4. Configuring Access Gateway to Inject OAuth Tokens

Enabling OAuth in Access Gateway

If you want Access Gateway to validate a token before granting access to a protected resource, you must enable OAuth for that protected resource.

Perform the following steps to enable OAuth in Access Gateway:

  1. Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name].

  2. Select the Protected Resources tab.

  3. Click the protected resource for which you want to enable OAuth.

  4. Select Validate OAuth Token.

  5. Click OK.

Configuring an Authorization Policy based on OAuth Scopes

You must configure an authorization policy and then assign it to the protected resource. Access Gateway makes decisions based on the rules defined in the authorization policy after validating the OAuth tokens.

Resources protected by OAuth tokens do not execute any authentication procedure. Hence, evaluation of policies associated with OAuth protected resources cannot fetch any user attributes outside the OAuth scope. All the user attributes needed for the protected resource must be part of the OAuth scope. Ensure that the proxy services protected by OAuth are not associated with any policies that refer to authentication contract, profiles, LDAP attribute, LDAP OU, roles, or RISK score. Any policy, which requests for data other than the scope of OAuth token fails.

Perform the following steps to configure an Authorization policy for scopes:

  1. Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name].

  2. Select the Protected Resources tab.

  3. Click the protected resource for which you want to configure an Authorization policy.

  4. Select the Authorization tab.

  5. Click Manage Policies > New.

  6. Specify a name for the policy and select Access Gateway: Authorization for the policy type.

  7. Click OK.

  8. Specify the following details:

    Field

    Action

    Description

    (Optional) Describe the purpose of this rule.

    Priority

    Specify the order in which a rule is applied in the policy, when the policy has multiple rules. The highest priority is 1 and the lowest priority is 10.

    NOTE:If two rules have the same priority, a Deny rule is applied before a Permit rule.

    Conditions

    Click New and then select OAuth Scopes.

    For Value, select the scope from the list.

    Actions

    Select one of the following options:

    • Permit: Allows the user to access the resource.

    • Deny: Select one of the following deny actions:

      • Display Default Deny Page: Displays a generic message, indicating that the user has insufficient rights to access the resource.

      • Deny Message: Allows you to provide a customized message that you want to display to users after denying their access attempts.

      • Redirect to URL: Allows you to specify a URL to redirect users after denying access. For example: http://www.example.com

    • Redirect: Specify the URL to which you want the users to redirect when they meet the conditions of this policy.

    • Re-authenticate with Contract: Allows you to specify an authentication contract used to authenticate the user.

  9. Click OK > OK.

  10. Select the policy you created and click Apply Changes > Close.

  11. Select the Authorization policy and click Enable > OK.

Configuring an Identity Injection Policy for OAuth Claims

You must configure an Identity Injection policy if you want to send the claims details to the resource server. Claims can include user attributes or permissions.

Perform the following steps to configure an Identity Injection policy for scopes:

  1. Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name].

  2. Select the Protected Resources tab.

  3. Click the protected resource for which you want to configure an Identity Injection policy.

  4. Select the Identity Injection tab.

  5. Click Manage Policies > New.

  6. Specify a name for the policy and select Access Gateway: Identity Injection for the type of policy.

  7. Click OK.

  8. Specify the following details:

    Field

    Action

    Description

    Specify the purpose of this policy.

    Priority

    Specify the sequence in which you want to apply the rule in the policy, if the policy has multiple rules. The highest priority is 1 and the lowest priority is 10.

    Action

    Click New, then select one of the following:

    • Inject into Authentication Header: Inserts the user name and password into the header. Select OAuth Claims under user name and then select a claim.

    • Inject into Custom Header: Inserts custom names into the custom header. Select OAuth Claims under Value and then select a claim.

    • Inject into Custom Header with Tags: Inserts custom tags with name/value content into the custom header. Select OAuth Claims under Tag Value and then select a claim.

    • Inject into Query String: Inserts a query string into the URL for the page. Select OAuth Claims under Tag Value and then select a claim.

    • Inject Kerberos Ticket: Inserts authentication values from the Kerberos ticket into the custom header. Select OAuth Claims under Value and then select a claim.

  9. Click OK > OK.

  10. Select the policy you created and click Apply Changes > Close.

  11. The Identity Injection page of the protected resource opens.

  12. Select the Identity Injection policy and click Enable > OK.

Configuring an Identity Injection Policy for User Passwords

Ensure that you have enabled the Allow admin to retrieve passwords option under Universal Password Retrieval in the eDirectory user store for all users, so that the policy can retrieve the password from the user store. Without this configuration, the identity injection policy for user password will not work.

The identity Injection policy that uses user passwords will not work when accessing a resource through the MobileAccess app because the MobileAccess app uses OAuth token for basic authentication. If you require to use Identity Injection with user password for MobileAccess, you can enable the password retrieval in eDirectory, which is less secure and not recommended. 

For more information about how to enable the password retrieval in eDirectory, see Universal Password Configuration Options in the Password Management Administration Guide.

NOTE:The password retrieval works only with eDirectory.

Perform the following steps:

  1. Click Devices > Access Gateway > Edit > [Reverse Proxy name] > [Proxy Service name].

  2. Select the Protected Resources tab.

  3. Click the protected resource for which you want to configure an Identity Injection policy.

  4. Select the Identity Injection tab.

  5. Click Manage Policies > New.

  6. Specify a name for the policy and select Access Gateway: Identity Injection for the policy type.

  7. Click OK.

  8. Configure the policy with the following details:

    • Action: Select Inject into Authentication Header.

    • User name: Select OAuth Claims > Access Token: User

    • Password: Select OAuth Claims > Password

  9. Click OK > OK.

  10. Select the policy you created and click Apply Changes > Close.

  11. Select the Identity Injection policy and click Enable > OK.

Configuring Access Gateway to Inject OAuth Tokens

See Section 6.4.9, Configuring an OAuth Token Inject Policy.

5.14.8 OAuth Scenarios

Web applications (Resource Server) validate an access token before allowing a client application to access resources

Identity Server (authorization server) issues an access token and web applications (hosted on the resource server) validate the token before granting a client application to access resources. This configuration is applicable in the following scenarios:

Web server authentication

In a typical web authentication model, a client application uses a resource owner’s credentials to access the resource owner’s information hosted on a server.

A resource owner allows a printing service (client application) to access personal photos stored at a photo sharing service (server), without sharing credentials with the printing service. The user authenticates directly with the photo sharing service that issues the printing service delegation-specific credentials.

For example, Alice accesses an application running on a web server at www.printphotos.example. She instructs it to print her photographs stored on a server at www.storephotos.example. The application at www.printphotos.example receives Alice's authorization consent for accessing her photographs without learning her authentication credentials of www.storephotos.example. This example is derived from OAuth RFC.

The following diagram illustrates the workflow of the web server authentication:

Accessing resources without using owner’s credentials:

OAuth allows a client application to access resources controlled by the resource owner and provides a method to obtain permission from resource owners to access their resources. Resource owners provide this permission in the form of a token and a matching shared-secret. The resource owner does not need to share credentials with the client application. Tokens are issued with a restricted scope and limited life.

For example, a user Alice has installed a gaming application that runs in her browser. She uses OAuth for accessing a social site at www.example.com. The gaming application updates scores in a database at www.example.com. The gaming application is registered with the social site and has an identifier. She has registered with the social site for identification and authentication. To upload Alice's scores, the gaming application accesses the score database when she authorizes it. When she accesses the page from the redirect URI in the game application, the authorization server sends the client ID, password, and authentication code received in the redirect request parameters to www.example.com, which in turn returns an access token to the game application. The gaming application sends the token to www.example.com to access Alice’s resources. www.example verifies the token and grants the gaming application access to Alice’s account for updating the scores.

This example is derived from OAuth RFC.

RESTful applications security

OAuth provides a way to secure REST APIs. For example, an enterprise acme.com exposes REST APIs. Using OAuth, acme.com can ensure that the right people have access to these APIs. In addition, it can enable applications to call APIs on behalf of a user. It can also revoke access to an API even if an application uses it.

Figure 5-20 OAuth Flow

The following is the workflow:

  1. The client application requests authorization from a user (resource owner). Client applications can make the authorization request directly to the resource owner or through the authorization server (Identity Server) as an intermediary.

  2. The client application receives an authorization grant from the authorization server. An authorization grant represents the resource owner's authorization. The user communicates the authorization by using one of four grants types (see OAuth Authorization Grant) or by using an extension grant.

  3. The client application authenticates itself at the authorization server, sends the authorization grant, and requests an access token.

  4. The authorization server authenticates the client application and validates the authorization grant. The authorization server issues an access token for a valid grant.

  5. The client application requests the resource server to provide access to the protected resource and authenticates this by presenting the access token.

  6. The resource server accepts the request for a valid token.

Access Gateway validates the Access token on behalf of web applications

This configuration is suitable when client applications want to access resources on legacy web applications.

For example, an enterprise acme.com has a multi-tier application: a front-end web application utilizing services from web service layers. The enterprise wants to protect these services and applications using OAuth and thereby need to place the RESTful API endpoints behind Access Gateway. The applications need to be modified to fetch OAuth token from Identity server. To minimize this change, Access Manager has the ability to enable Access Gateway to fetch OAuth tokens on behalf of the application and pass it over to the application via HTTP header. Now, the application can simply take the token from the header and use it to invoke the web service.

Figure 5-21 Work flow

  1. A client application requests access to a web resource and provides authentication details to Identity Server.

  2. Identity Server authenticates the client application, gets the user’s consent, generates an OAuth token, and sends the token to the client application.

  3. The client application provides the token to Access Gateway.

  4. Access Gateway sends the token to Identity Server for validation.

  5. If the token is not valid, Access Gateway returns a 401 error.

  6. If the token is valid, Access Gateway performs the following tasks:

    1. Executes the authorization policy, if configured, based on OAuth scopes or claims.

    2. Sends user attributes and grants details provided to the client application to the web application by using the Identity Injection policy, if configured.

  7. The resource server returns a response to Access Gateway and Access Gateway sends this response to the client application.

Access Gateway injects the Access token on behalf of web applications

This configuration is used when Access Gateway injects access tokens into the authorization header.

Figure 5-22 The following diagram illustrates the workflow:

  1. The user sends request to access a web application protected by Access Gateway.

  2. Access Gateway redirects the user to Identity Server, which prompts for user authentication.

  3. On successful authentication, Access Gateway shares the session details with Identity server to fetch the OAuth token.

  4. Identity server authenticates the session details and issues an access token to Access Gateway.

  5. Access Gateway injects the access token into the authorization header.

5.14.9 Mobile Authentication

Applications on a mobile device request for authentication and the web server redirects you to the authorization server to authenticate and authorize the server to access your data. When you approve, the web server receives an Access token as part of the redirect URL. After the authorization server grants the token, the application can access the protected data with the Access token. Less confidential applications, such as mobile clients or thick clients use this authentication. For more information about mobile applications, see Section 9.0, Enabling Mobile Access.

5.14.10 Exchanging SAML 2.0 Assertions with Access Token

Access Manager supports SAML 2 bearer grant. Access Manager supports only the authorization grant flow for assertion and the assertion is used for authenticating the user.

You can use SAML 2 assertions to request an access token. Access Manager validates the assertion and generates an access token for accessing OAuth protected resources.

Consider a scenario where a user requires to access an OAuth protected resource and the user is already authenticated using SAML assertion. To access the resource, the user requires to re-authenticate and give consent.

To avoid re-authentication and getting consent from user again, the application can use Access Manager to exchange the SAML 2 assertion with access token.

To use assertions for requesting an access token, you must configure the settings required for the assertion issuer. The assertion issuer is the identity provider that issues the SAML assertion. You can import the settings of Identity Server acting as a SAML identity provider or use any other third-party identity provider as an assertion issuer.

NOTE:

  • The access token received after exchanging with assertion includes the scopes based on the previous user consent that can be from using the authorization code flow.

  • The token time-out is based on the assertion time-out. For example, if an assertion is issued for 10 minutes and after 2 minutes the token is requested, the token is valid for 8 minutes.

    If an assertion is valid for longer duration, you can exchange the assertion with access token multiple times.

  • The assertion must be encoded with Base64 URL.

Configuring Assertion Issuers

An assertion issuer is an identity provider that issues an assertion.

  1. Click Devices > Identity Server cluster > OAuth & OpenID Connect > Assertion Issuers.

  2. Click the Add Assertion Issuer icon.

  3. (Conditional) If you want to add assertion issuer that is existing as a trusted identity provider under SAML 2, WS-Trust, or WS Federation, click Import Configuration from Existing IDP.

    Some of the values of the fields specified in Step 5 get auto-populated. You can modify the values if required and specify the values for the remaining fields.

    NOTE:In an assertion, a user is identified based on the SAML 2 name identifier and not the SAML 2 attributes. You must configure the name identifier for the required Assertion Issuer.

  4. (Conditional) To use a self-issued assertion (an assertion generated by a client application), click Create New Assertion Issuer.

  5. Specify the following details:

    • Issuer Name: The name of the identity provider that generates the assertion.

    • Entity ID: The entity ID that identifies the identity provider.

    • Audience Alias: This is used for identifying the intended audience. Authorization server’s token endpoint is the intended audience by default. If the assertion does not contain the Identity Server’s token endpoint as the audience, you can configure an audience alias. The default value is https://<DNS name>:8443/nidp/oauth/nam/token.

    • Issuer Signing Certificate: This gets auto-populated if you have imported an existing trusted identity provider’s configuration. If you are creating an assertion issuer, click Upload Certificate to upload the signing certificate used by the identity provider.

      NOTE:If there are multiple certificates available for the trusted Identity provider, the first certificate is imported.

    • Selected UserStores: This is used for identifying the users in an assertion. You can choose a list of user stores from the available list.

  6. Select the required name identifiers in the assertion.

    • Persistent: Select this option if the assertion includes the name identifier in the persistent format. You can choose the required LDAP attribute that is used as the persistent value in the assertion.

      NOTE:Access Manager supports only the LDAP attribute as persistent value.

    • Email: Select this option if the assertion includes the name identifier in email format. You can choose the required LDAP attribute that is used as the email value in the assertion.

    • Unspecified: Select this option if the assertion includes the name identifier in unspecified format. You can choose the required LDAP attribute that can be used as the unspecified value in the assertion.

For information about requesting a token, see the NetIQ Access Manager 5.0 Administration API Guide.

5.14.11 Encrypting Access Token

Access Manager generates OAuth 2 access token in the JWT format. You can choose to encrypt this token or use it without encryption. You can also choose who can validate the access token.

Access Manager generates an access token, then encrypts the access token by using a random symmetric key. This encrypted token includes the key in plain text and can be encrypted by using either the Access Manager or the resource server key. The Access Manager signing public key information is displayed in JSON Web Key Set Endpoint, which you can view on the EndPoint Summary page of Administration Console.

The access token can include user attribute or custom claims based on the resource server’s requirement. This helps when you encrypt an access token by using the resource server key. The resource server can decrypt and validate the token without the need to request for user attribute information from Access Manager.

NOTE:The size of the token is variable. You must ensure that the token size does not increase when you are using multiple user attributes or claims along with a specific algorithm.

Access Manager can encrypt the access token by using any of the following methods.

NOTE:By default, Access Manager encrypts the access token with Access Manager key. To use resource server key to encrypt the access token, an OAuth request must contain the resourceServer parameter. If a request is sent without the resourceServer parameter, then Access Manager uses its key to encrypt the token.

Encrypting the Token with the Access Manager Key

If you want a resource server to contact an authorization server for validating an OAuth token, you can encrypt the token by using Access Manager keys. This is the default encryption method.

Access Manager encrypts a token by using a random symmetric key, then the encrypted token is signed by using an Access Manager private key. When resource server consumes an access token, it requests Identity Server to validate the token.

Encrypting the Token with the Resource server Key

If you want the resource server to decrypt and validate the OAuth token, you can encrypt the token by using resource server key.

You can encrypt an OAuth token by using the resource server’s key available on resource server’s JWKS (JSON Web Key Set) or a specific URL. To use resource server key, you must specify the resource server key or key set in Identity Server. When the access token is consumed, the resource server validates the token by decrypting the token. This gives the resource server the ability to decrypt the token without having to go to the authorization server (Identity Server) to decrypt or validate the token.

The following diagram illustrates how Access Manager leverages the resource server to decrypt a token:

  1. Access Manager generates an unencrypted JWT token that includes Header, Payload, and Signature.

  2. The token encryption algorithm specified in the resource server’s JSON Web Key Set is used for generating random symmetric key to encrypt this token.

    This encrypted token contains the random key information in plain text.

  3. Retrieve the JWKS information from the resource server.

  4. Access Manager uses resource server public key that is defined in resource server’s JWKS to encrypt the random key information that is in plain text.

    To view the Access Manager signing public key details in Administration Console, click OAuth & OpenID Connect > EndPoint Summary.

  5. The resource server consumes the encrypted token.

  6. The resource server uses its corresponding private key to decrypt the random key information.

    The resource server uses the random key to decrypt the token. For more information about sample Java code to decrypt the token and validating token signature, see the Access Manager API guide.

5.14.12 Configuring Multi-Factor Authentication for Resource Owner Credentials Grant

Access Manager supports multi-factor authentication for the Authorization Code flow and Implicit flow. Access Manager 5.0 onwards, you can also invoke multi-factor authentication for Resource owner credential flow. This authentication flow is applicable only for Plug-in-based Advanced Authentication (Smartphone and Voice Call) methods.

Perform the following steps to configure multi-factor authentication for Resource Owner Credentials Grant:

  1. Create an authentication class. See Creating Authentication Classes.

    NOTE:Only Smartphone and Voice Call classes are supported.

  2. Create a method and contract. See Configuring Authentication Methods and Configuring Authentication Contracts.

    NOTE:While creating the method, you can use the MAXRETRY and RETRYTIMEOUT properties to configure authentication timeout. For more information, see Optional Properties (KEY/Value) for Authentication Methods.

  3. Navigate to Devices > Identity Server > Edit > OAuth & OpenID Connect > Global Settings.

  4. Under Contracts for Resource Owner Credentials Authentication, assign the Name/Password contract and the contract you created in Step 2.

    or

    (Client application developer) In the client application token request, send the contract URI in the acr_values parameter.

    This scenario is useful when you want to restrict the contract for specific client applications.

For more information about Resource owner credentials authentication contract, see Defining Global Settings.

5.14.13 Viewing Endpoint Details

Under Devices > Identity Servers > Edit > OAuth & OpenID Connect > EndPoint Summary, you can view the following endpoints:

  • Authorization EndPoint: Enables client applications to interact with the resource owner and obtain an authorization grant. It is located on an authorization server.

  • Registration EndPoint: Enables registering client applications on the authorization server. It is located on the authorization server.

  • Token EndPoint: Enables client applications to obtain an access token by providing its authorization grant or refresh token. It is located on an authorization server. This endpoint supports SAML bearer assertion. A SAML assertion can be sent to this endpoint to generate a token.

  • TokenInfo Endpoint: Enables the resource server to validate access and refresh tokens when the client sends the token. Also, you can get the details of the tokens to introspect the token.

    This endpoint is deprecated. To validate and check the status of the access or the refresh tokens, send the request to Token Introspect Endpoint.

  • Token Introspect Endpoint: Enables the protected resource server to check the status and details (meta-information) of an access or a refresh token. This endpoint provides the token status in the JSON format. For details about request and response, see Token Introspect Endpoint in the Access Manager 5.0 OAuth Application Developer Guide.

  • UserInfo EndPoint: Provides information about the user associated with the access token in the standard OpenID Connect format.

  • OpenID Metadata EndPoint: Provides information about OpenID provider metadata. It includes information about supported algorithms, authorization endpoints, scope, response type, response mode, and authentication methods. For example, this lists the supported Proof Key for Code Exchange by OAuth Public Clients (PKCE) methods, code_challenge_methods_supported":["plain","S256"]. For more information about PKCE flow, see API documentation.

    NOTE:If a scope does not require users’ permission, claims_supported and scopes_supported fields of the metadata do not display defined claims and defined scopes.

  • Revocation Endpoint: Enables Authorization server to revoke refresh tokens (JWT) and its corresponding access tokens (JWT) with the defined claims.

  • JSON Web Key Set Endpoint: Provides the information about the signing certificate that is used by Access Manager.

NOTE:As per OAuth specifications, endpoints must not accept any non-HTTPS request. However, Access Manager supports non-HTTPS requests also. This is required to enable OAuth in scenarios when Access Manager is deployed behind a third-party SSL accelerator.

5.14.14 OAuth and OpenID Connect Audit Events

Access Manager provides the following OAuth audit events:

  • OAuth & OpenID Token Issued

  • OAuth & OpenID Token Issue Failed

  • OAuth Consent Provided

  • OAuth Consent Revoked

  • OAuth Client Applications

  • OAuth & OpenID Token Validation Success

  • OAuth & OpenID Token Validation Failed

  • OAuth Refresh Token Revocation Success

  • OAuth Refresh Token Revocation Failed

For more information about auditing the events, see Enabling Identity Server Audit Events.

5.14.15 Enabling Logging for OAuth and OpenID Connect

  1. Click Devices > Identity Servers > Edit > Auditing and Logging.

  2. Select Enabled under File Logging.

  3. In the Component File Logger Levels section, specify any one of the following options for OAuth and OpenID Connect:

    • Off: Turns off component file logging

    • Severe: Logs serious failures that can stop system processing

    • Warning: Logs potential failures that have minimal impact on execution.

    • Info: Logs informational events.

    • Verbose: Logs static configuration information

      The system logs any configuration errors under one of the primary three levels: Severe, Warning, and Info.

    • Debug: Logs events for all of the preceding levels (Severe, Warning, Info, and Verbose)

  4. Click OK.

5.14.16 Managing Client Applications by Using REST API

For information about managing client applications by using REST API, see Managing Client Applications in the NetIQ Access Manager 5.0 Administration API Guide.

5.14.17 Managing OAuth 2.0 Resource Server and Scope by Using REST API

For information about registering, deleting, and viewing registered resource servers along with creating, modifying, deleting, and viewing configured scopes, see Registering a Resource Server in the NetIQ Access Manager 5.0 Administration API Guide.

5.14.18 Revoking Refresh Tokens and the Associated Access Tokens

You can revoke a refresh token, which helps in revoking the associated access tokens. To revoke refresh tokens, use the REST API calls to the token revocation endpoint. For information about using REST calls to revoke a refresh token, see the NetIQ Access Manager 5.0 Administration API Guide.

For the MobileAccess application, use the Access Manager user portal for unregistering a device. For example, a user who lost a registered device can unregister the device from the user portal page. However, if you are not using MobileAccess, ensure that the user is logged out of OAuth. To achieve this, the API request for the access token must include the device ID and user details. If the device ID is specified during the request, you can revoke the refresh token for the configured device. For information about API requests, see the NetIQ Access Manager 5.0 Administration API Guide.

NOTE:You can revoke only the refresh tokens that are in the JWT format.

5.14.19 Configuring the Demo OAuth Application

This application demonstrates how to protect an OAuth enabled application by using Access Manager. This application contains a RESTful web service and a client application that uses this RESTful web service.

The RESTful web service allows you to perform TODO tasks for a hypothetical application. This web service exposes an API to add, modify, and delete tasks on behalf of a user. The client application provides a web interface that uses REST APIs to manage these tasks. The REST service protects REST APIs with OAuth Access tokens issued by a trusted Access Manager OAuth provider.

This demo configuration provides a way to test OpenID connect endpoints such as metadata, userinfo, and tokeninfo endpoints.

Download OAuth 2.0 Demo Application and follow the instructions provided in the RunningDemoApp document.