5.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 NetIQ Access Manager 4.4 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.4 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. From 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

These tokens contain a user’s signed assertions. 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.

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. (Application Developer)

  6. Register the client application in Access Manager. You can register a client by using Administration Console (Administrator), Identity Server (Application Developer or Administrator), or REST API (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. (Application Developer or Administrator)

  9. Deploy the resource server. (Application Developer)

  10. Deploy the client application. (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:

  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.

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

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

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

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

    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 because this attribute stores the refresh token information that can be used later to check for revocation. Ensure that no other application uses this attribute.

    CORS Domains

    Select any one of the following options based on your 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.

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

    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

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

    Access-Control-Allow-Credentials Header

    This option is available in Access Manager 4.4 SP2 and later.

    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 available in Access Manager 4.4 Service Pack 3 and later)

    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.

    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.4 SDK Guide.

  3. Click OK.

Configuring a Resource Server

Access Manager allows you to define settings for each resource server. A resource server validates and accepts tokens sent by client applications, and then grants 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

Perform the following steps for a resource server that uses Identity Server as the authorization 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 algorithm does not match with the available algorithms for the keys in the resource server’s JWKS or URL, Access Manager fails to encrypt 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 and then set up claims or permissions for each scope. When a user grants client applications access to protected resources, they can perform actions based on permissions defined in the scope.

For example, you can define a scope named email and define 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.

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 permission from the user to access a resource.

    Require user permission

    Select this option if this scope requires user’s permission before providing access to the protected resources.

    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 3.5.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 select Add to Access Token.

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

  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 custom claim that should be added to the access token, then select Add to Access Token.

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

      NOTE:If an access token was issued before removing a claim, the client will continue to use the token with the available claims.

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

  • Administration Console: Only an Access Manager Administrator can manage the client applications through Administration Console. The user must request the Access Manager administrator to register a client application using Administration Console.

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

    An application developer must log in to Identity Server for registering a client application.

    The My Applications tab lists all the applications that you added. You can view details, modify, and delete applications.

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

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

    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. Click Token Timeout Configuration.

    You can use this option if you want to choose specific time-out duration for a specific client application instead of using the duration mentioned in the global settings. You can specify time-out information for the following settings:

    • Authorization Code Timeout

    • Access Token and ID Token Timeout

    • Refresh Token Timeout

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

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

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

  6. Click Advanced OpenID Connect. This is an optional step. Specify the following details:

    Field

    Description

    JSON Web Key Set URI

    Specify the URI of the JSON file containing the JSON web keys.

    ID Token Signed Response Algorithm

    Specify the ID Token Signed Response Algorithm.

    ID Token Encrypted Response Algorithm

    Specify the algorithm used to encrypt the key.

    ID Token Encrypted Response Enc

    Specify the algorithm used to encrypt the content.

  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:

  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:

    • 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 8.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 5-17 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 5-18 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 5-19 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 7.0, Enabling Mobile and Web 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 a SAML identity provider that is configured in the same Identity Server 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.4 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 JSON Web Key Set 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.

  • 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. This will list the supported Proof Key for Code Exchange by OAuth Public Clients (PKCE) methods. For example, code_challenge_methods_supported":["plain","S256"]. For information about PKCE flow, see API documentation.

  • Revocation Endpoint: Enables Authorization server to revoke refresh tokens and its corresponding access tokens.

  • 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 20.2, 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.4 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.4 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.4 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.4 Administration API Guide.

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.