Authenticating and authorizing through a redirect URL

You can use a service that is hosted externally from IBM® API Connect to collect authentication and authorization details from your user when an application requests access on that user's behalf.

About this task

If you use methods for authentication that are not supported by IBM API Connect, you can redirect users to a suitable URL at which they can authenticate. The user is then returned to the OAuth process after authentication and authorization have been confirmed.

The following illustration indicates the transaction flow for third party authentication.

1. The application initiates a request to access an API protected with a third-party entity. IBM API Connect redirects the application with an HTTP 302 redirect based on identity extraction -> redirect -> redirect-url, for user authentication (and optional authorization).
2. The application communicates directly with the third-party entity to gather user identity. IBM API Connect is not involved in this communication. After the third-party entity finishes processing authentication (and optional authorization), it returns an HTTP 302 redirect that uses the original-url from the request, with the username and confirmation code appended.
3. IBM API Connect receives the request that includes the username and confirmation code, and communicates with the authentication URL, based on authentication -> x-ibm-authentication-url, to confirm user identity before the request is completed.
4. An HTTP 200 response from the third-party entity allows IBM API Connect to continue the OAuth 2.0 request process as if the owner is authenticated. The request is then processed according to the grants type.
   • - accessCode returns a temporary code to the application.
   • - implicit returns the access token to the application.
   For any response other than HTTP 200, the request fails with a statement added to the error log.

Note: The API Manager UI also includes the ability to create and edit security definitions. However, the preferred method for these tasks is by using the API Designer UI, as described here. Any steps that are specific to a particular UI are marked with an icon.

To create an external form, and to indicate the URL to which API Connect will redirect users, complete the following instructions:

1. Create your service for authentication and authorization. Use the URL of the landing page of this service as your redirect URL.
   1. To include elements in your form that are provided by API Connect, use the query parameters from the URL that your user is redirected to.
      Except for original-url, all other parameters are provided only as information for the third-party entity to use or ignore. When a user is redirected to your page, the URL includes any of the following parameters that contain a value:

      app-name

      The name of the application requesting access, as provided through the Developer Portal.

      appid

      The id of the application requesting access.

      catalog

      The name of the catalog where the product is being used by the application.

      catalogid

      The id of the catalog where the product is being used by the application.

      catalogtitle

      User-friendly display name for the catalog.

      g-transid

      Same definition as transid. This parameter is provided only if its content is different from transid.

      org

      The name of the developer organization that hosts the application.

      orgid

      The id of the developer organization that hosts the application.

      orgtitle

      User-friendly display name for the organization.

      original-url

      The original URL that the user was directed to by the application, including query parameters from the original URL that are necessary for standard OAuth 2.0 requests. You can include these parameters in your service to provide information to the user. Additionally the rstate is appended. The rstate is a hash code that is generated by API Connect for verification purposes. The URL is URL-encoded and must be decoded before further use, the rstate should be left unchanged.

      provider

      The name of the API provider organization.

      providerid

      The id of the API provider organization.

      providertitle

      User-friendly display name for the provider organization.

      requested-scope

      [optional] If Application Scope check is enabled and replaces the scope from the initial application request, this field holds the scope value from the initial application request, and the new replacement scope value is put into original-url.

      transid

      Transaction id used in the gateway for the transaction that triggers this call.

      The URL to which the user is sent to when they are redirected to your page has the following form:

      Redirect_URL?original-url=Original_URL&rstate=R_State&app-name=Application_Name

      with variables as described in the preceding list of query parameters. API Connect does not enforce a size limit on the length of the Redirect URL.
   2. Create the stages of authentication, authorization, and any intermediate stages that you require to take place before you allow access to the application. Upon completion of these stages, redirect the user to the Original_URL and append a user name, their confirmation code, and the application name to be evaluated for access grant or denial by API Connect. The confirmation code does not have a size limit enforced by API Connect.
      Original URL requires the following form:

      Original_URL&username=User_Name&confirmation=Confirmation_Code

      where all variables are as described previously.

      For example:

      
      https://your_gateway.com/your_org/your_catalog/your_api/oauth/authorize?response_type=code&redirect_uri=https://example.com/redirect&scope=/your_api&client_id=5af57a4a-6db9-4141-ad08-5709432af66e&rstate=5yXZSNocRPpJm9MZHR15MDc9hZhTiSRy10EhV28&username=spoon&confirmation=12345678
      

   3. To send your own error responses after the authentication and authorization service, redirect the user to the Original_URL and append an error code. You can also append a user name. Use the following form:

      Original_URL&username=User_Name&error=Error_Response

      where Error_Response is the message you wish to send and all other variables are described as previously.

      For example:

      https://your_gateway.com/your_org/your_catalog/your_api/oauth/authorize?response_type=code&redirect_uri=https://example.com/redirect&scope=/your_api&client_id=5af57a4a-6db9-4141-ad08-5709432af66e&rstate=5yXZSNocRPpJm9MZHR15MDc9hZhTiSRy10EhV28&username=User&error=access_denied

2. Create a service to validate the confirmation code and user name. API Connect makes a GET call to your authentication URL after the user is redirected back to the authorization URL. When the call is made, it includes in its authorization header the user name and confirmation code you supplied previously. Confirm that these are correct and respond with an HTTP success code such as 200 OK if you want to allow access, or non-200 HTTP response code, such as 401 Unauthorized to deny access.
3. Click APIs.
   The APIs tab opens.
4. 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 .
5. Click Drafts in the UI navigation pane, and then click APIs.
   The APIs tab opens.
6. In your OAuth 2.0 provider API, supply the redirect URL that is used in Step 1 and the authentication URL that is used in Step 2. For more information on configuring your provider API, see Creating an OAuth provider API, Steps 10.d and 10.e.