Protecting an API with OAuth security definition

When you create an OAuth security definition in an API, you provide settings for controlling access to the API operations through the OAuth authorization standard.

To create an OAuth security definition, complete the following steps:

1. Click APIs.
   The APIs tab opens.
2. If you have not previously pinned the UI navigation pane then click the Navigate to icon .
   The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon .
3. Click Drafts in the UI navigation pane, and then click APIs.
   The APIs tab opens.
4. To create the security definition in an existing API, click the API you want to work with. To create a new API to add the security definition to, see Creating API definitions.
5. Navigate to the Security Definitions section.
6. In the Security Definitions section, click the Add Security Definition icon .
7. Select OAuth.
   A new OAuth definition is created.
8. Configure your new security definition.
   1. In the Name field, provide a name for your OAuth definition to replace the default name.
   2. Optional: In the Description field, provide a description of your OAuth definition.
   3. For the Flow drop-down menu, select Implicit, Password, Application, or Access Code depending on the required OAuth security definition grant type.
   4. Specify the authorization url endpoint.
   5. If you select a grant type of Access Code, you are provided with an additional entry field in the user interface, named token URL endpoint.
      Note: The authorization url endpoint and token URL endpoint are maintained only for informative purposes, no validation or other action is applied to them by API Connect.
   6. Complete one or both of the following steps depending on the OAuth security definition grant type:
      • For Password, Access Code, and Application flows: in the Token URL field, provide the URL of your OAuth provider API's token Path.
        The token path takes the following form:

        Host_Address/Organization_Segment/Catalog_Segment/API_Base_Path/Token_Path

        where:

        • Host_Address is the address of your gateway host.
        • Org_Segment is the path segment of the organization that you want to use.
        • Catalog_Segment is the path segment that is used by the Catalog you intend to publish your API in.
        • API_Base_Path is the base path of the OAuth provider API.
        • Token_Path is the path of either of your token operations. Typically, this is oauth2/token.
      • For Access Code and Implicit flows: in the Authorization URL field, provide the URL of your OAuth provider API's authorization Path.
        The authorization path takes the following form:

        Host_Address/Org_Segment/Catalog_Segment/API_Base_Path/Auth_Path

        where:

        • Host_Address is the address of your gateway host.
        • Org_Segment is the path segment of the organization that you want to use.
        • Catalog_Segment is the path segment that is used by the Catalog you intend to publish your API in.
        • API_Base_Path is the base path of the OAuth provider API.
        • Auth_Path is the path of your authorization operation. Typically, this is oauth2/authorize.
9. You can use either scope or introspect URL to verify an access token. If the access token is generated by the IBM® API Connect platform, use scope. If the access token is generated by a third party entity, use the introspect URL.

   Scope validation

   • Define any scopes that you want to cover access to your API.
     • In the Scopes section, click the Add scope icon .
     • Enter the name of the scope.
     • Enter a description.
   • Set Advanced Scope Check.
     • Use the Enable Scope Check slider to set the option to provide extra scope verification in addition to previously defined Scope settings. For more information, see OAuth Scope.
     Note:

     All scopes listed by the security definition of the secured API must be granted by the access token issued by your API Connect OAuth provider.

   • Define the introspect endpoint by entering an introspect URL. An introspect endpoint is what API Connect uses to verify a token issued by a third party OAuth provider.
     Note: The introspect URL conforms to the OAuth 2.0 specification: https://tools.ietf.org/html/rfc7662 with regards to requests and responses. This feature also provides a header to pass additional information to your provider, see Integrating third party OAuth provider.
10. Configure your security settings.
    1. In the Security section, click the Add icon to create additional options.
11. Click the Save icon to save your changes.