4.2.10 Understanding How Access Manager Uses OAuth and OpenID Connect

Access Manager Identity Server acts as the authorization server to issue access token to a client application based on 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 4.5 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.

This section explains how to use the OAuth 2.0 and OpenID Connect protocol to set up Identity Server as the authorization server. The following are the topics included in this section:

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 that 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.

OAuth Keywords and Their Usage in Access Manager

This section includes all the basic terminologies that are used in the proceeding sections.

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.

The client application can request for an access token by using API calls. For details about API requests and response, see NetIQ Access Manager 4.5 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.

Access Manager 4.3 and earlier versions supported refresh tokens in a binary format. Access Manager 4.4 onwards, the newly issued refresh token will be a JWT token. If you are upgrading from 4.3 or earlier versions, you can continue using the already issued access tokens with the corresponding binary refresh tokens.

NOTE:If you require Identity Server to issue the tokens in JWT format, you must ensure the following:

that all the nodes of Identity Server cluster are upgraded and that you update the cluster from Administration Console.

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 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.

Implementing OAuth in Access Manager

The following diagram depicts the implementation flow of OAuth in Access Manager:

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

OAuth Implementation
  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 client application by using Administration Console, see Registering 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 basic 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.

Configuring OAuth and OpenID Connect

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

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

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.

To enable OAuth and OpenID Connect, perform the following steps:

  1. Click Devices > Identity Servers > Edit.

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

  3. Click OK.

  4. Update Identity Server.

NOTE:For OAuth authorization, Identity provider 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 information about a client application, which a user authorizes to access attributes and resources. This information is unique per user. So, you need to store it as part of a User Object in the user store. If you already have an attribute, you can 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 will store 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.

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.

Example for extending the schema of a user object in Active Directory

  1. In Windows, Start > Run > mmc.

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

  3. Select Active Directory Schema, then click Add.

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

  5. In the Create New Attribute dialog box, 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.

Example for 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.

  14. Click Apply > OK.

  15. 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, grants, and so on.

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

  2. You can configure and view the following details on this page:

    Field

    Description

    Issuer

    Specify the name of the authorization server. This name will be 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: If you want 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: If you want to allow access for requests from any domains.

    • Limit to: If you want 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: Used to obtain a new access token when an Access token becomes invalid or expires.

    Token Revocation

    This option is enabled by default. 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. In case you do not want to use this attribute or do not have write access to this attribute, you must disable this option.

    NOTE:The revocation of binary tokens is not supported.

    Perform Revocation Check After

    (Access Manager 4.5 Service Pack 2 and later versions)

    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.

    Authorization Code Timeout

    Specify the duration in minute after how long 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.

    You cannot add an external certificate to OAuth because Access Manager Appliance does not have an option to assign the certificates to a keystore. The certificates available in nam-keystore can only be used.

    Contracts for Resource Owner Credentials Authentication

    Select the supported contracts from the Available contracts list and move them to the Contracts Field.

    This option allows the administrator to configure the Resource Owner flow to execute specific authentication contract. It supports Name/Password based contracts only.

    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 NetIQ Access Manager 4.5 SDK Guide.

  3. Click OK.

Configuring a Resource Server

Access Manager allows you to define the settings for encrypting an access token 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 can validate and accept tokens sent by client applications, and then grant access to resources.

Access Manager also allows you to 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

The 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.

Consider a scenario where 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 RS1.

Resource Server

Encryption mechanism

Scopes

RS1

Encrypt using Access Manager key

Scope1

RS2

Encrypt using resource server key

Scope2

Now, 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

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

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

  2. Click New.

  3. Specify a name for the resource server.

  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 values for the following fields:

    For understanding the use of the following fields, see Encrypting the Token with Resource server Key.

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

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

    • 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.

  6. Click Next.

    Continue with Defining Scopes for a Resource Server.

Restricting the Number of Requests

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

Open /opt/novell/nam/idp/conf/tomcat.conf. 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.

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 the user claims such as user attributes and permissions. The client application developer can request for required scopes, which the administrator can use 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. Hence, 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 OAuth scope and use them to inject with the Identity Injection policy. Role attribute is calculated when the token is sent to UserInfo Endpoint.

  • If you have registered 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.

  4. 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 the user’s claim that should 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:Virtual attributes can be used for LDAP based attributes and for constant values.

    • 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 will not include the scopes that require user permissions. Hence, deselect this option.

    NOTE:If you deselect this option, the scope will not get listed in the scopes_supported field of the metadata endpoint. Also, the claims_supported field of the metadata endpoint will 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.

  5. Click Next.

    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:

    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 more information about creating an attribute set, see Section 2.3.1, 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 already 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. You can select the required claim that should be added to the access token, then select Add > Add to Access Token.

      To remove a specific claim from the 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. You can select the required claim that should 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:The claims are not added to or removed from an already 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.

      If you require to remove claims from both the tokens, then after selecting the claims 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 the access and the ID tokens.

Modifying Scopes of a Resource Server

You can modify the scopes of a registered resource server. Access Manager allows you to delete a resource server or delete the scope of a resource server.

To modify scopes of a resource server, perform the following steps:

  1. Click Devices > Identity Server > Edit > OAuth & OpenID Connect > Resource Server. This page lists all registered resource servers.

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

  3. On the Edit Scope page, modify the details as required. For more information about the fields on this page, 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 more information about user attributes and claims, see Defining Scopes for a Resource Server.

Registering OAuth Client Applications

A client application that sends API requests to Access Manager must be registered with Access Manager Identity Server. As part of the registration, specify the client name, redirections (URIs), and any other provider-specific data required by the API. 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 the applications that the user has added. You 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

Perform the following steps to register a client application:

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

  2. 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 the revocation_id parameter is not included in the request, the user cannot use the persistent cookie to authenticate from client B.

    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 (This is supported only for the authorization code flow).

    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 token type that the authorization server will return to this client application. The following are available tokens:

    • Code

    • ID Token

    • Refresh Token

    • Access Token

    Refresh Token

    Select Always Issue New Token to issue a new refresh token on every refresh token request.

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

    • JSON Web Key Set URI: If you require to encrypt the ID token using the public key of the client application, then 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 ID token to a client application. If you require Identity Server to sign the ID token using a JWS algorithm, then 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 in the Global Settings page, Signing Algorithm is RS256, then select RS256 in this field.

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

    • ID Token Encrypted Response Algorithm: Specify the JWE algorithm that is required 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.

      This is the JWE enc algorithm that is required to encrypt the content of the ID token.

  4. Click Token Configuration.

    You can use this option to specify the required token format for the access and the refresh tokens. Also, you can use this option if you want to choose a specific timeout duration for a specific client application instead of using the duration mentioned in the global settings:

    • Authorization Code Timeout: Specify the duration after which the authorization code will expire.

    • Access Token and ID Token Timeout: Specify the duration after which the access and the ID token 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 JWT token, but you can select any of the following options based on the client application requirement:

      NOTE:This option is available in Access Manager 4.5 Service Pack 1 and later.

      • Default: Select this option to use the token format as either binary or JWT. The format will be set based on the value you set in the OAUTH TOKENS IN BINARY FORMAT property of the Identity Server. The values are described in the proceeding table:

        OAUTH TOKENS IN BINARY FORMAT

        Format of the Token

        Set to true

        Binary

        Set to false

        JWT

        Unspecified

        JWT

        When you update the value or add the OAUTH TOKENS IN BINARY FORMAT property, any client application with the Default option will consequently receive the succeeding tokens (access and refresh) in the changed format.

      • Binary: Select this option if the client application requires the tokens in binary format. When you select this option, the token format will always be binary irrespective of the value set in the OAUTH TOKENS IN BINARY FORMAT property of the Identity Server.

        The binary tokens are always encrypted using Access Manager keys. To validate the token, the resource server uses the Access Manager UserInfo and the TokenInfo endpoint.

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

        • Encrypting 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: This is the recommended format. Select this option if you require the client application to use tokens in JWT format. When you select this option, the token format will always be JWT irrespective of the value set in the OAUTH TOKENS IN BINARY FORMAT property of the Identity Server.

  5. Click Consent Screen Configuration.

    Specify the following details:

    Field

    Description

    Client Logo URL

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

    Privacy Policy URL

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

    Terms of Service URL

    Specify the URL of the terms of service.

    Contacts

    Specify email addresses of people related to this client application.

  6. Click Authorized JavaScript origins (CORS) and add Domains. The domains configured here can access restricted resources available on the client application. This is an optional step. 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

  7. Click Register Client.

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

Modifying Registered Client Applications

To modify a registered client application, perform the following steps:

  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

    • Delete a registered client application

    • Modify details of a registered client application.

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

  3. Click Modify Client.

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.

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:

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 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:

    • 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.

    The Authorization page of the protected resource opens.

  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 then 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.

    The Identity Injection page of the protected resource opens.

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

Configuring Access Gateway to Inject OAuth Tokens

To configure Access Gateway to inject OAuth tokens, see Section 10.4.9, Configuring an OAuth Token Inject Policy.

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 resource server) validate the token before granting a client application to access the resources. This configuration is suitable in the following scenarios:

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

    For example, a user (resource owner) can allow a printing service (client application) to access private photos stored at a photo sharing service (server), without sharing credentials with the printing service. Instead, the user authenticates directly with the photo sharing service that issues the printing service delegation-specific credentials.

    For example, a user named Alice accesses an application running on a web server at www.printphotos.example and instructs it to print her photographs that are 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.

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

    NOTE:This example is derived from the OAuth RFC document.

  • Accessing resources without using owner’s credentials: OAuth allows a client application to access resources that are controlled by the resource owner and provides a method to obtain permission from the resource owners to access their resources. The 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 named Alice has installed a gaming application that runs in her browser and 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. Alice has registered with the social site for identification and authentication. To upload Alice's scores, the gaming application accesses the score database when Alice authorizes it. When Alice 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.

    NOTE:This example is derived from the OAuth RFC document.

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

Figure 4-18 OAuth Flow

  1. The client application requests authorization from the 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 4-19 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 the Access tokens into the authorization header.

Figure 4-20 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.

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 8.0, Enabling Mobile Access.

Exchanging SAML 2 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 the 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 either import the settings of Identity Server acting as a SAML identity provider or use any other 3rd 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 the assertion is issued for 10 minutes and after 2 minutes the token is requested, the token will be valid for the remaining 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. In this section you can add the assertion issuers and specify the details.

  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. Hence, 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 values for the following fields:

    • 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 the token, see the NetIQ Access Manager 4.5 Administration API Guide.

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, the 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 Access Manager Key

If you want the resource server to contact the 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 the token by using a random symmetric key, then the encrypted token is signed by using an Access Manager private key. When resource server consumes the access token, it requests Identity Server to validate the token.

Encrypting the Token with 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 the facility to decrypt the 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. 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.

Viewing Endpoint Details

In Administration Console Dashboard 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 the 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 a JSON format. For details about the request and response, see Token Introspect Endpoint in the Access Manager 4.5 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 user’s permission, the claims_supported field and the scopes_supported field of the metadata does not display the defined claims and the defined scopes respectively.

  • 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.

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 Section 21.4, Enabling Identity Server Audit Events.

Enabling Logging for OAuth and OpenID Connect

To enable logging for OAuth and OpenID Connect events, perform the following steps:

  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.

Managing Client Applications by Using REST API

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

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 4.5 Administration API Guide.

Revoking Refresh Tokens and the Associated Access Tokens

You can revoke a refresh token, which helps in revoking the associated access tokens. To revoke the refresh tokens you need to 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 4.5 Administration API Guide.

If you are using the MobileAccess application, you can 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, then you must 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 more information about API requests, see the NetIQ Access Manager 4.5 Administration API Guide.

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

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.