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.

Before you begin

To complete this task, you will need to either create or have created an OAuth security definition that uses Implicit grant type or Access Code (Authorization Code) grant type. For more information, see Creating an OAuth security definition.

About this task

If you use methods for authentication that are not supported by 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.
Figure 1. Third party authentication (AU) and authorization (AZ) transaction flow
Illustration of third party authentication and authorization flow.
  1. The application initiates a request to access an API protected with a third-party entity. 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. 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. 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 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.

Procedure

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. You will 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 following query parameters from the URL that your user is redirected to.
      Note: With the exception of original-url, none of these parameters are included in the URL automatically; you must add them as required.
      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.
      org
      The name of the consumer organization that hosts the application.
      orgid
      The id of the consumer 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 state_nonce is appended. The state_nonce is a hash code generated by API Connect for verification purposes. The URL is URL-encoded and should be decoded before further use, the state_nonce should remain 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 GW for the transaction which trigger 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&state_nonce=R_State&app-name=Application_Name
      where all variables are as described previously. The Redirect URL does not have a size limit enforced by API Connect.
    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&state_nonce=HoIbRG+6bZtqlB7LDkq4gjlD3SHKglCbnYdHs/bMz2Y=&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&state_nonce=HoIbRG+6bZtqlB7LDkq4gjlD3SHKglCbnYdHs/bMz2Y=&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. In your OAuth provider configuration, 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 an OAuth Provider, see Configuring a native OAuth provider when using API Manager or Configuring a native OAuth provider when using Cloud Manager.