Configure OAuth Using the Fusion Applications Identity Domain

All Fusion Application users are available in Fusion IAM domain automatically through synchronization, and OAuth is available when an extension sends a request to access Fusion Applications REST APIs.

OAuth uses a generated token (a JSON Web Token, shortly known as JWT) to grant access to the required resources. The process to get that token involves a few steps. Use the Oracle Cloud Infrastructure Identity and Access Management identity domain associated with your Fusion Applications instance to configure the OAuth flow. In this topic, you'll find the configuration instructions along with explanatory content to help you understand the overall setup.

At a high-level, the configuration involves the following:

1. Identify the identity domain where you'll create your confidential application. The domain will be the authorization server.
   Note: Make sure that you or other required users have the necessary privileges to access the Identity and Access Management Admin Console to navigate to the identity domain.
2. Specify grant types that decide the OAuth flow. You can configure a 2-legged OAuth or a 3-legged OAuth based on your requirement.
3. Define the scope of the access.
4. Generate the access token.
5. Use the token to access the REST resources.

2-Legged OAuth and 3-Legged OAuth

Both 2-legged and 3-legged configurations generate the OAuth token required to access the REST resources. However, your decision to pick one of them is based on how you want to authorize the access to the REST resources.

In a 2-legged OAuth configuration, if you want an application (known as OAuth client) to directly access the REST resources, you can do so using the Client Credentials grant type. In this configuration, you store the client credentials with the application, which on your behalf can request the authorization server to provide the access token. Later, that token is used to request access to the REST resources on the resource server. In this case, there's no user involvement. But if you want the user to be involved and use a password to authorize the request for an access token, you can use the Resource Owner grant type. The following illustrations will help you understand the differences between these two grant types of 2-legged OAuth flow.

On the other hand, a 3-legged OAuth is potentially an interactive browser flow that's also secure. The resource owner needs to be already authenticated or needs to authenticate through the configured sign in procedure and optionally can be asked to authorize the application or the OAuth client to access the resources. If the resource owner is already authenticated, there's no need to enter any credentials. The OAuth client must be registered with the authorization server (in this case the identity domain). In this flow, the request is routed through an authorization server where the resource owner optionally needs to authorize it. The authorization server then passes an authorization code to the OAuth client. The OAuth client sends the authorization grant code along with its preassigned client credentials to the authorization server. Upon successful verification, the authorization server generates an access token and shares it with the OAuth client. Finally, the client passes the access token to the resource server to access the resources.

The following illustration explains the flow.

Grant Types and OAuth Mapping

A grant type is an important component in the OAuth flow. It's used to retrieve the access token from the authorization server. The OAuth framework supports different grant types, based on how the resources are accessed. Some grant types are suited for 2-legged OAuth implementation and others are meant for use in the 3-legged OAuth implementation. The following table lists the commonly used grant types for implementing OAuth in cloud applications.

Authorization Grant Type	Description	Used in 2-legged OAuth	Used in 3-legged OAuth
Resource owner	In this case, the resource owner's credentials are obtained beforehand and stored in the client application. The client application is a trusted application with the authorization server. When the request to the authorization server is made, the resource owner's credentials are validated and the access token is returned.	Yes	No
Authorization code	In this grant type, a client application uses its registered client ID to request an authorization code from the authorization server. It then passes the client credentials along with the received authorization code to obtain an access token which in turn will be used to access the resources from the resource server.	No	Yes
Client credentials	The client application uses the client credentials to directly request the resource server for access. The verification happens within the authorization server against the registered client application, and the access token is returned to the client application.	Yes	No
JSON Web Token (JWT) Assertion	A client application requests for a user assertion JWT from a token service that must be registered with the authorization server. The client sends the JWT to the authorization server's token endpoint to request access to the resources. The authorization server verifies the JWT and issues the access token to the client application.	Yes	No

For detailed information about the supported grant types, see

• Access Grant Types in Oracle Cloud Infrastructure Documentation.
• Access Grant Types in REST API for Oracle Identity Cloud Service.

Configure OAuth Using Authorization Code Grant Type (3-Legged OAuth)

In the case of an Authorization Code (3-legged OAuth) configuration, the involved parties are: the user, the application, the authorization server, and the resource server. For the user to get authorized, the application must be registered with the authorization server (in this case Fusion Applications identity domain). Therefore, you'll need to create a confidential application that can be accessed by multiple users but can keep the OAuth credentials confidential and protected. Let's look at how to do this in the application.

Caution: Never change the name of the OAuth token issuer.

1. Register your client and resource applications with the authorization server.
   1. Sign in to the Fusion Applications identity domain as an Administrator.
   2. From the list of identity domains, click Integrated applications and click Add application.
   3. On the Add application dialog box, select Confidential Application and click Launch workflow.
   4. On the Add Confidential Application page, enter a name for the application that you're adding.
   5. In the URLs section, although the fields are marked as optional, you can add details that you think are necessary.
   6. In Displays Settings, select the relevant option.
   7. In the Authentication and Authorization section, select the Enforce grants as authorization checkbox to allow access to the confidential application only if the user has been earlier granted access. Otherwise, leave it unselected.
   8. Click Next.
   9. In the Configure OAuth section, select Configure this application as a client now to proceed with the client configuration settings.
   10. In the Authorization section, select the Authorization code checkbox to specify the grant type.
   11. Enter a value for the Redirect URL field. This is the application URL (appended with the authorization code as URL parameter) to which the user is taken to after authentication.
   12. Optionally, add the Logout URL and Post-Logout URL if those are necessary.
   13. To identify the type of the client application, keep Confidential as the default selected value.
   14. Select the applicable Allowed operations. Read the field-level help for details on which option to choose. If none is required, you can proceed without making any selection.
   15. In the ID token encryption algorithm, select if you require the token to be encrypted. The default value is None.
   16. Use the toggle to enable the Bypass consent functionality. If you enable it, the resources won't require the consent of the resource owner before the user is granted access to the resources, even if the resource has been configured to require user consent.
   17. Select the relevant option for the Client IP address. You can leave them unselected if none is relevant.
   18. In the Token issuance policy section, select All or specific based on whether the user needs access to all the resources or only those which are allowed.
2. Add resources for your product.
   1. Select the Add resources checkbox to include the resources that are accessible to the users.
   2. In the Resources subsection, click Add scope.
   3. On the Add scope dialog box, select the applications containing the resources, and click Add. The resources are added. You'll notice that the scope is defined in the format: <resource audience name><resource scope name>.
   4. Review the added resources. If you don't need any resource, select and click Remove to exclude it from the scope.
3. Complete application creation and activate the application.
   1. After adding the resources, click Next and go with the default settings for the Web tier policy section.
   2. Click Finish. A confirmation dialog box appears displaying the auto-generated Client ID and the Client Secret values.
      Note: Make a note of the Client ID and Client Secret values because you'll need them for requesting the access token.
   3. Click Close. You're taken to the application page that you just created.
   4. Click Activate. A confirmation message appears asking for a confirmation to activate the application.
   5. Click Activate application. The confidential application is activated and ready for use.
4. Request an access token. You can do so using a client application such as Postman or a cURL command. Let's look at both these options.

   Using Postman

   Using cURL

   In Postman, create a new request. On the Authorization tab, select OAuth 2.0 as the Authorization Type. In the Configure New Token section, enter the following client configuration: Token Name: Enter a generic name for the token. Grant Type: Set the grant type to Authorization Code. Callback URL: Enter the Redirect URL value collected from IDCS. Select the Authorize using browser checkbox to authorize the token generation through the browser. Auth URL: The IDCS URL appended with /oauth2/v1/authorize is used as the Auth URL. You can get the URLs from https://idcs-<idcs-id>.identity.oraclecloud.com/.well-known/idcs-configuration. Access Token URL: The IDCS URL appended with /oauth2/v1/token is used as the Access Token URL. You can get the URLs from https://idcs-<idcs-id>.identity.oraclecloud.com/.well-known/idcs-configuration. Client ID: Enter the Client ID value collected from IDCS. Client Secret: Enter the Client Secret value collected from IDCS. Scope: Mention the scope defined in the identity domain. Client Authentication: Select Send as Basic Auth Header. Click Get New Access Token. Postman passes on the information to the identity domain to authenticate and returns the access token.

   Open a browser and send a request to obtain the authorization code using this URL: https://<domainURL>/oauth2/v1/authorize?response_type=code&client_id=<clientid>&redirect_uri=<redirect url>&scope=<scope> The browser gets redirected to the <redirect URL> specified in the confidential application. In the URL path, you can find the authorization code as a parameter. Copy the authorization code for use later in step c. Launch the command prompt. Enter the cURL command below, replacing the text in angle brackets ( < > ) with the appropriate values: curl -u <clientid:clientsecret> --basic -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --request POST https://<domainURL>/oauth2/v1/token -d "grant_type=authorization_code&code=<authorization code>&redirect_uri=<redirect url>" You can expect the response in a format as shown here: Status: 200 "access_token":"eyJ4NXQiOiI4Wk. . ." "token":"Bearer", "expires_in":3600 Copy the value displayed for access_token. This is the token that you'll need to request access to the resources.

5. Access the resource using the access token.
   In Postman, click Use Token to use the token (auto-fill the Token field) and access the resources from the resource server. Or, if you used the cURL command in the previous step, you could continue with the command prompt to send the REST request and get access to the resources. You'd need to structure your request as shown here:

   curl -X GET
      -H "Content-Type:<as needed by your REST endpoint, such as, application/json>"
   
      -H "Authorization: Bearer <access_token>"
   
      "https://<REST API endpoint URL>"
   

   Note that the Authorization header is set to Bearer token and you'd provide the access token retrieved earlier as its value.

Configure OAuth Using Client Credentials Grant Type (2-legged OAuth)

If you're setting up an application that's going to process requests without any user intervention, and which doesn't need to use the user permissions in the requests, you can use the Client Credentials grant type to set up a 2-legged OAuth flow. In this scenario, the client credentials are stored in the application itself so that the authorization server can validate it without requiring any response from the user. Typically, this setup is recommended for a client-server interaction handling automated application-level requests. Let's look at how to set it up in the application.

Caution: Never change the name of the OAuth token issuer.

1. Create an application that allows users to access the resources.
   1. Sign in to the identity domain as an Administrator.
   2. From the list of identity domains, click Integrated applications and click Add application.
   3. On the Add application dialog box, select Confidential Application and click Launch workflow.
   4. On the Add Confidential Application page, enter a name for the application that you're adding.
   5. In the URLs section, although the fields are marked as optional, you can add details that you think are necessary.
   6. In Displays Settings, select the relevant option.
   7. In the Authentication and Authorization section, select the Enforce grants as authorization checkbox to allow access to the confidential application only if the user has been earlier granted access. Otherwise, leave it unselected.
   8. Click Next.
   9. In the Configure Single Sign-on section, select Configure this application as a client now to proceed with the client configuration settings.
   10. In the Authorization section, select the Client credentials checkbox to specify the grant type.
   11. Select the applicable Allowed operations. Read the field-level help for details on which option to choose. If none is required, you can proceed without making any selection.
   12. In the ID token encryption algorithm, select if you require the token to be encrypted. The default value is None.
   13. Select the relevant option for the Client IP address. You can leave them unselected if none is relevant.
   14. In the Token issuance policy section, select All or specific based on whether the user needs access to all the resources or only those which are allowed.
2. Add resources for your product.
   1. Select the Add resources checkbox to include the resources that are accessible to the users.
   2. In the Resources subsection, click Add scope.
   3. On the Add scope dialog box, select the applications containing the resources, and click Add. The resources are added. You'll notice that the scope is defined in the format: <resource audience><resource scope>.
   4. Review the added resources. If you don't need any resource, select and click Remove to exclude it from the scope.
3. Complete application creation and activate the application.
   1. After adding the resources, click Next and go with the default settings for the Web tier policy section.
   2. Click Finish. A confirmation dialog box appears displaying the auto-generated Client ID and the Client Secret values.
      Note: Make a note of the Client ID and Client Secret values because you'll need them for requesting the access token.
   3. Click Close. You're taken to the application page that you just created.
   4. Click Activate. A confirmation message appears asking for a confirmation to activate the application.
   5. Click Activate application. The confidential application is activated and ready for use.
4. Request an access token. You can do so using a client application such as Postman, or cURL command. Let's look at both these options.

   Using Postman

   Using cURL

   In Postman, create a new request. On the Authorization tab, select OAuth 2.0 as the Authorization Type. In the Configure New Token section, enter the following client configuration: Token Name: Enter a generic name for the token. Grant Type: Select Client Credentials. Access Token URL: The IDCS URL appended with /oauth2/v1/token is used as the Access Token URL. You can get the URLs from https://idcs-<idcs-id>.identity.oraclecloud.com/.well-known/idcs-configuration. Client ID: Enter the Client ID value collected from IDCS. Client Secret: Enter the Client Secret value collected from IDCS. Scope: Mention the scope defined in the identity domain. Client Authentication: Select Send as Basic Auth Header. Click Get New Access Token. Postman passes on the information to the identity domain to authenticate and returns the access token.

   Launch the command prompt. Enter the cURL command below, replacing the text in angle brackets ( < > ) with the appropriate values: curl -u <clientid:clientsecret> --basic -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --request POST https://<domainURL>/oauth2/v1/token -d "grant_type=client_credentials&scope=<scope>" You can expect the response in a format as shown here: Status: 200 "access_token":"eyJ4NXQiOiI4Wk. . ." "token":"Bearer", "expires_in":3600 Copy the value displayed for access_token. This is the token that you'll need to request access to the resources.

5. Access the resource using the access token.
   In Postman, click Use Token to use the token (auto-fill the Token field) and access the resources from the resource server. Or, if you used the cURL command in the previous step, you could continue with the command prompt to send the REST request and get access to the resources. You'd need to structure your request as shown here:

   curl -X GET
      -H "<as needed by your REST endpoint, such as application/json>"
   
      -H "Authorization: Bearer <access_token>"
   
      "https://<REST API endpoint URL>"
   

   Note that the Authorization header is set to Bearer token and you'd provide the access token retrieved earlier as its value.

Configure OAuth Using Resource Owner Grant Type (2-legged OAuth)

If you're operating in a very secure and trusted environment, you can use the Resource Owner grant type OAuth flow. In this model, the resource owner prefers to authenticate the request directly in the client application instead of redirecting it to an identity provider. The client is a trusted application registered with the authorization server. When the authorization server receives the request, it validates the resource owner's credentials and returns the access token to the client. Let's look at how to set it up in the application.

Caution: Never change the name of the OAuth token issuer.

1. Create an application that allows users to access the resources.
   1. Sign in to the identity domain as an Administrator.
   2. From the list of identity domains, click Integrated applications and click Add application.
   3. On the Add application dialog box, select Confidential Application and click Launch workflow.
   4. On the Add Confidential Application page, enter a name for the application that you're adding.
   5. In the URLs section, although the fields are marked as optional, you can add details that you think are necessary.
   6. In Displays Settings, select the relevant option.
   7. In the Authentication and Authorization section, select the Enforce grants as authorization checkbox to allow access to the confidential application only if the user has been earlier granted access. Otherwise, leave it unselected.
   8. Click Next.
   9. In the Configure Single Sign-on section, select Configure this application as a client now to proceed with the client configuration settings.
   10. In the Authorization section, select the Resource owner checkbox to specify the grant type.
   11. Select the applicable Allowed operations. Read the field-level help for details on which option to choose. If none is required, you can proceed without making any selection.
   12. In the ID token encryption algorithm, select if you require the token to be encrypted. The default value is None.
   13. Use the toggle to enable the Bypass consent functionality. If you enable it, the resources won't require the consent of the resource owner before the user is granted access to the resources.
   14. Select the relevant option for the Client IP address. You can leave them unselected if none is relevant.
   15. In the Token issuance policy section, select All or specific based on whether the user needs access to all the resources or only those which are allowed.
2. Add resources for your product.
   1. Select the Add resources checkbox to include the resources that are accessible to the users.
   2. In the Resources subsection, click Add scope.
   3. On the Add scope dialog box, select the applications containing the resources, and click Add. The resources are added. You'll notice that the scope is defined in the format: <resource audience name><resource scope name>.
   4. Review the added resources. If you don't need any resource, select and click Remove to exclude it from the scope.
3. Complete application creation and activate the application.
   1. After adding the resources, click Next and go with the default settings for the Web tier policy section.
   2. Click Finish. A confirmation dialog box appears displaying the auto-generated Client ID and the Client Secret values.
      Note: Make a note of the Client ID and Client Secret values because you'll need them for requesting the access token.
   3. Click Close. You're taken to the application page that you just created.
   4. Click Activate. A confirmation message appears asking for a confirmation to activate the application.
   5. Click Activate application. The confidential application is activated and ready for use.
4. Request an access token. You can do so using a client application such as Postman, or cURL command. Let's look at both these options.

   Using Postman

   Using cURL

   In Postman, create a new request. On the Authorization tab, select OAuth 2.0 as the Authorization Type. In the Configure New Token section, enter the following client configuration: Token Name: Enter a generic name for the token. Grant Type: Select Password Credentials. Access Token URL: The IDCS URL appended with /oauth2/v1/token is used as the Access Token URL. You can get the URLs from https://idcs-<idcs-id>.identity.oraclecloud.com/.well-known/idcs-configuration. Client ID: Enter the Client ID value collected from IDCS. Client Secret: Enter the Client Secret value collected from IDCS. User name: Enter the user name. Password: Enter the password of the user. Scope: Mention the scope defined in the identity domain. Client Authentication: Select Send as Basic Auth Header. Click Get New Access Token. Postman passes on the information to the identity domain to authenticate and returns the access token.

   Launch the command prompt. Enter the cURL command below, replacing the text in angle brackets ( < > ) with the appropriate values: curl -u <clientid:clientsecret> --basic -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --request POST https://<domainURL>/oauth2/v1/token -d "grant_type=password&username=<username>&password=<password>&scope=<scope>" You can expect the response in a format as shown here: Status: 200 "access_token":"eyJ4NXQiOiI4Wk. . ." "token":"Bearer", "expires_in":3600 Copy the value displayed for access_token. This is the token that you'll need to request access to the resources.

5. Access the resource using the access token.
   In Postman, click Use Token to use the token (auto-fill the Token field) and access the resources from the resource server. Or, if you used the cURL command in the previous step, you could continue with the command prompt to send the REST request and get access to the resources. You'd need to structure your request as shown here:

   curl -X GET
      -H "<as needed by your REST endpoint, such as application/json>"
   
      -H "Authorization: Bearer <access_token>"
   
      "https://<REST API endpoint URL>"
   

   Note that the Authorization header is set to Bearer token and you'd provide the access token retrieved earlier as its value.