40 Configuring REST API Support

Learn about the configurations required on OUD Instance for OUD Data Management and SCIM REST API support.

This section contains the following topics:

• Configuring the Server Instance For REST API Support
• Configuring OAM as OAuth Identity Provider in OUD

40.1 Configuring the Server Instance For REST API Support

You can configure the OUD instance for Data Management and SCIM REST API support.

OUD exposes Data Management and SCIM interface through HTTP(S) connection handlers.

Note:

For Admin REST API, see Administering Oracle Unified Directory Using REST API.

Do either of the following to enable the connection handlers:

• Configuring Connection Handlers During the OUD Instance Setup: See Configuring Data Management REST API.
• Configuring Connection Handlers for an Existing OUD Instance: See Configuring Data Management REST API.

40.2 Configuring OAM as OAuth Identity Provider in OUD

OUD supports configuring Oracle Access Management (OAM) as an Open Authorization (OAuth) identity provider.

The following content applies only to OUD Bundle Patch 12.2.1.4.230928 and later releases.

In addition to the basic authentication technique, OUD supports OAuth 2.0 JWT Access Tokens from OAM for OUD Data Management and SCIM REST API authentication. You can use the JWT token as the Bearer token in calls to OUD Data Management and SCIM REST APIs.

This section discusses the following topics:

• Understanding OAuth Services Authorization
• Configuring OAuth Services

40.2.1 Understanding OAuth Services Authorization

The OAM OAuth 2.0 Service is an open standard OAuth protocol which deals with only delegated authorization.

The following roles are supported by OAuth that helps secure access to protected resources:

• Resource Server: The server hosting the protected resources, capable of accepting and responding to resource requests using access tokens. The Resource Server is deployed in a different location from OAM and the Client.
• Resource Owner: This is an entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.
• Client: It is an application making protected resource requests on behalf of the resource owner and with its authorization.
• OAuth Services: Refers to the Authorization Server, Oracle Access Management. The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

OAuth 2.0 adds an authorization layer and separates the client's role from that of the resource owner.

In OAuth 2.0, the client seeks access to resources controlled by the resource owner and hosted by the resource server, and is provided credentials that differ from those of the resource owner. To access protected resources, the client acquires an access token - a string identifying a certain scope, duration, and other access attributes - rather than disclosing the credentials of the resource owner. Third-party clients are granted access tokens by an authorization server with the approval of the resource owner. The client utilizes the access token to gain access to the resource server's protected resources. This scenario is referred to as a 3-legged OAuth flow as it involves a resource owner approving a request for resources. See Understanding 3-Legged Authorization.

40.2.2 Configuring OAuth Services

You must first configure the OAuth Services before you can use the authorization protocol.

Perform the following steps to configure the OAuth Services.

1. Setting Up OAuth Services in OAM
2. Setting Up OAM as OAuth Identity Provider in OUD
3. Invoking the REST APIs

40.2.2.1 Setting Up OAuth Services in OAM

This section describes the high-level tasks in setting up OAuth in OAM.

Prerequisite for OAuth Configuration

Before you can configure OUD, you must first configure OAuth Services in OAM and perform the prerequisites mentioned as follows.

1. Create an identity domain using REST API calls, see Creating an Identity Domain.
2. Register a new resource using REST API calls, see Creating a Resource.

   Note:

   You must configure the resource name and scopes created here in OUD also. For example, a Resource Server named OUDResourceServer has been created and the scopes read and write are set.
3. Create a trusted client using REST API calls, see Creating a Client.

For more information on OAuth REST APIs, See REST API for OAuth in Oracle Access Manager and Managing the Oracle Access Management OAuth Service and OpenIDConnect.

40.2.2.2 Setting Up OAM as OAuth Identity Provider in OUD

You can set up OAM as OAuth Identity Provider in OUD.

Perform the following steps to configure OAM as OAuth Identity Provider in OUD.

1. Run the dsconfig command-line utility with create-identity-provider subcommand to create OAM as the OAuth Identity Provider in OUD and enable it.

   dsconfig create-identity-provider  \
   --set enabled:true \
   --set identity-mapper:Exact\ Match  \
   --set oauth-resource-server:OUDResourceServer  \
   --set oauth-scope:OUDResourceServer.read  \
   --set oauth-token-issuer:http://host4:7777/oauth2  \
   --type oauth \
   --provider-name OAMProvider \
   --hostname localhost \
   --port 4444  \
   --portProtocol LDAP \
   --bindDN "cn=Directory Manager" \
   --bindPasswordFile /home/oracle/pwd.txt \
   --trustAll \
   --no-prompt
   

   Table 40-1 OAuth Identity Provider Configuration in OUD

   Parameter	Description
   oauth-resource-server	Refers to the name of the Resource Server during creation in OAM. See Step 2 in Setting Up OAuth Services in OAM.
   oauth-scope	Refers to the scopes configured for the Resource Server during creation in OAM. This is a multi-valued argument. See Step 2 in Setting Up OAuth Services in OAM. Note: The Resource Server name must be prefixed to the scope when the values are provided. For instance, OUDResourceServer.read.
   oauth-token-issuer	Refers to the OAuth Token Issuer URL from OAM. This can be retrieved using the OpenIDConnect Discovery Endpoint from OAM. For more information on the Discovery Endpoint, see OpenIDConnect Authentication Flows in Oracle Access Manager.
   identity-mapper	An Identity Mapper needs to be configured to map the user ("sub" claim) in the JWT Token to a valid user in OUD. To create an identity mapper, see Overview of Identity Mappers.
   oauth-provider	Refers to the name of the OAuth 2.0 compliant Identity Provider. Currently OUD only supports OAM. Therefore, the default value is OAM.
   oauth-token-x5t-algorithm	Refers to the algorithm that is used to generate the thumbprint of an Identity Provider's X.509 certificate. Note:The access token header should include the thumbprint generated using the same algorithm. The default value is SHA-1, which assumes that the access token header contains an x5t property with the value set to the SHA-1 fingerprint of the certificate. However, if the access token issued by the Identity provider lacks the x5t property and only contains the x5t#256 property, the value here should be SHA-256.
   token-introspection-endpoint	Refers to the URL for the OAuth token introspection endpoint. This is an optional parameter. When configured, the OAuth Server is also queried to ensure that the JWT Token is genuine. To obtain the OAM OAuth token introspection endpoint, use the OpenIDConnect Discovery Endpoint. This must be a POST operation. For instance, http://host4:7777/oauth2/rest/token/introspect.
   custom-claim-to-id-mapper	Refers to the name of the custom claim in the Access Token that will be utilized by the identity-mapper to map to a valid user record in OUD. This is an optional parameter, which if not configured, sub in the token claim is mapped automatically.

2. Set the http-authentication-scheme in REST Server Extension to include the bearer in addition to basic scheme.

   dsconfig set-extension-prop \
   --extension-name REST\ Server  \
   --add http-authentication-scheme:bearer \
   --hostname localhost \
   --port 4444  \
   --portProtocol LDAP \
   --bindDN "cn=Directory Manager"  \
   --bindPasswordFile /scratch/nenekris/OUD/pwd.txt \
   --trustAll \
   --no-prompt

   Note:

   The REST Server Extension is enabled by default; if it is not, see Configuring the Server Instance For REST API Support.
3. Import the public key certificates (JWT token signing keys) of OAM into OUD's JKS truststore so that OUD can perform signature validation of the JWT Tokens when presented in a REST API call.

   Note:

   The OAM's trust certificate can be obtained using OpenIDConnect Discovery Endpoint using the jwks_uri: http://<ManagedServerHost>:<ManagedServerPort>/oauth2/rest/security

   For more information on the Discovery Endpoint, see OpenIDConnect Authentication Flows in Oracle Access Manager.

40.2.2.3 Invoking the REST APIs

You can invoke the Data Management or SCIM REST APIs for OAuth.

This following sample REST requests show how to invoke the OUD Data Management REST API using the cURL command to send a request to https://<OUD HOST>:<HTTP Port>/rest/v1/directory with a specific payload.

With basic authentication:

curl -X GET -u '<userdn>':<password> http://<OUD Host>:<HTTP Port>/rest/v1/directory/dc=example,dc=com?scope=sub&filter=(objectclass=*) -H 'cache-control: no-cache' -H 'content-type: application/json' 

With Bearer token in the header:

curl -X GET -H "Authorization: Bearer {token}" http://<OUD Host>:<HTTP Port>/rest/v1/directory/dc=example,dc=com?scope=sub&filter=(objectclass=*) -H 'cache-control: no-cache' -H 'content-type: application/json'