Add OAuth Scopes to REST API Endpoints

OAuth scopes limit access granted by the Authorization server to an application/user. An application/user can request one or more scopes when requesting an access token. Upon successful authentication, the access token issued will be limited to the web services associated with the scopes.

OAuth Scopes in EmpowerID

There are three components involved with OAuth scopes in EmpowerID. These are as follows:

1. Web Service – REST APIs created in Workflow Studio and published as protected app resources

2. Application – Protected Application Resource of SSO Type OAuth

3. OAuth client application – OAuth application which issues ClientID, Client Secret, API Key

In EmpowerID, scopes are assigned on a Protected Application Resource level. A protected application must be bound to an OAuth client application. Custom OAuth scopes are defined, and appropriate web services are assigned to the scope. When an application or user requests for an access token with defined scopes, the issued access token will be granted access to all the web services assigned to the requested scopes.

This topic demonstrates how to configure an OAuth scope for an application created in EmpowerID. To follow along, you will do the following:

1. Create a number of custom API REST endpoints/web services in Workflow Studio

2. Create an OAuth client application in EmpowerID

3. Create a Protected Application Resource in EmpowerID and bind the newly created OAuth client application to it

4. Add scope items for the custom API REST endpoints/web services to the Protected Application Resource

5. Assign the scope items to the web services

6. Grant access to the web services

Step 1 – Create custom REST API endpoints in Workflow Studio

Create custom API REST endpoints/web services for EmpowerID in Workflow Studio, such as those listed in the below table. Please note that these endpoints are examples. Replace these with your endpoints.

Step 2 – Create an OAuth Client application

1. On the navbar of the EmpowerID Web interface, expand Single Sign-On > SSO Connections and select OAuth /OpenID Connect.

2. From the EmpowerID OAuth Client Apps tab of the OAuth page, click the Add button.
   
   

   Open

   

    

3. Under the General tab of the OAuth Provider Application Details page fill in the following:

   • Name – Name of the application

   • Display Name – Display name for the application

   • Description – Description for the application

   • Application Type – Select the appropriate application type from the drop-down.

   • Application Owner – Person creating the app by default; or, search for another person

   • Issuer – Defaults to EmpowerID; you can update the value to any string / URL you want.

   • Signing Certificate – Select a certificate with a private key from the EmpowerID certificate store

4. Click Save to create the application.

Step 3 – Add Client Secrets and Callback URLs to the app

1. After EmpowerID creates the application, expand the Client Secrets accordion and click the blue Add button in the grid header.
   
   

   Open

   

    

2. Copy the string in the Client Secret field.
   

   
   
   

    

3. After you have copied and saved the Client Secret, enter the following information:

   1. Name – Name of the secret

   2. Expires – Select I Year, 2 Years or Never.

4. Click Save to create the secret.

5. Expand the Callback URLs accordion.

6. Click the blue Add button in the Callback URLs accordion and then enter https://<yourserver>/WebIdPForms/OAuth/V2, replacing <yourserver> with the FQDN of your EmpowerID Web server. Add any other Callback URLs supported by your application. Callback URLs are case-sensitive.

7. Click Save to close the dialog.
   
   

    

8. Copy and save the Client ID and API Key values.
   
   

    

Step 4 – Create an SSO app for the client app

1. On the navbar, under Single Sign-On, select Applications.

2. From the Actions pane, click Create Application.
   
   

    

3. Under the General tab of the Application Details page fill in the following:

   • Name – Name of the application

   • Display Name – Display name for the application

   • Description – Description for the application

   • Create a Tracking Only Account Store – Select this option to create an account store for the application.

   • Creation Location – Click the Select a Location link and then select and save the desired creation location for the application.

4. Click Single Sign-On tab of the Application Details page, do the following:

   1. Single Sign-On Connection Type – Select OAuth / OpenID Connect.

   2. OAuth Client Application – Search for and select the OAuth Client application you created above.

   3. Click Add to Cart.
      
      

       

5. Click the Cart icon at the top of the page to open the cart.

6. Enter a reason for creating the application and then click Submit.
   
   

    

Step 5 – Add OAuth Scopes

1. Click the Find Applications breadcrumb on the Application Details page to return to the Find Applications page.

2. Search for the application you just created and click the Display Name link for it.
   
   

    

3. On the Application Details page that appears, select the SSO tab and expand the Scopes (OAuth) accordion.
   
   

    

4. Click the Add button on the grid header.

5. Add the following scopes (replace with your own):

   • eidbot.computer

   • eidbot.creds

   • eidbot.otp

   • eidbot.registration

   • eidbot.secrets
     
     

      

6. Expand the Scope to API Mappings accordion and click the Add button in the grid header.
   
   

    

7. In the API Info dialog that opens, do the following:

   • Scope – Search for and select the desired scope.

   • Protected API Endpoint – Search for and select the appropriate endpoint.

   • Click Save.
     
     

      

8. Repeat step 7 and assign scopes to the rest of the web services you registered in Workflow Studio.

Step 6 – Grant access to the web services

As with all resources protected by EmpowerID, API endpoints or web services are secured by the RBAC engine. This means that users with access to an endpoint cannot call or consume it. As this is the case, to test calling the endpoint and to make it available to your users, you need to create RBAC delegations for users who will be consuming your custom API endpoints.

1. On the navbar, expand Role Management and select Manage Delegations.

2. Select the Resource Delegations tab.

3. Do the following in the delegations form to grant access to your endpoints:

   1. Resource Type – Select Web Service

   2. Enter a Web Service to Search – Search for and select an endpoint

   3. To Which Type of Actor Do You Wish to Assign Access – Select the appropriate actor type (Person, Business Role and Location, Group, Management Role, Management Role Definition, Query-Based Collection)

   4. Click the Add button in the grid header and then search for and select the appropriate actor. For example, if you selected Business Role and Location as the actor type, you search for the specific Business Role and Location.

   5. Access Level – Select Executor

   6. Click Save.

4. Repeat Step 3 for each of your endpoints.