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 must have created an API. For more information, see Creating API definitions.
Additionally, you will need to either create or have created an OAuth security definition that
uses Implicit Flow or Authorization Code Flow. For more information, see Protecting an API with OAuth security definition.
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.
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.
Procedure
To create an external form, and to indicate the URL to which API Connect will redirect users, complete the
following instructions:
Create your service for authentication and authorization. Use the URL of the landing page of
this service as your redirect URL.
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:
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.
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.
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:
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.
Click APIs.
The APIs tab opens.
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 .
Click Drafts in the UI navigation pane, and then click APIs.
The APIs tab opens.
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.