Securing your APIs with OpenID Connect
OpenID Connect (OIDC) is built on top of the OAuth 2.0 protocol and focuses on identity assertion. OIDC provides a flexible framework for identity providers to validate and assert user identities for Single Sign-On (SSO) to web, mobile, and API workloads.
About this task
OIDC uses the same grant types as OAuth (implicit, password, application and access code) but uses OIDC specific scopes, such as openid, with optional scopes to obtain the identity, such as email and profile. OIDC generates a JSON Web Token (JWT), rather than an opaque token with OAuth, that can optionally be signed and encrypted.
IBM® API Connect for IBM Cloud supports OIDC provider flow by building on top of the existing OAuth 2 provider capabilities. The additional OIDC functions are provided by using the API Connect for IBM Cloud API Assembly, which provides the flexibility to fully configure the protocol to meet your desired requirements.
A pre-supplied sample OAuth Provider API is provided for you to download and adapt, rather than creating your own from scratch. You must modify this API in accordance with your OIDC configuration.
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.
Import the pre-supplied sample OAuth Provider API as follows:
- Click .
- Click Or import from URL and in the URL field enter https://raw.githubusercontent.com/ibm-apiconnect/openid/master/oidc_1.0.0.yaml
The specified YAML file is imported, and the associated API definition, called OAuth 2 OIDC Provider, opens in the Design view.
Click the OAuth 2 OIDC Provider API and examine the API as follows:
In the navigation pane, click Paths to display the paths that have been defined for the API.
The token API is exposed on the paths
/oauth2/token. The path
/oauth2/introspectlets you obtain information about the access token.
In the navigation pane, click OAuth 2.
The default grant types are supported, but of particular importance are the available scopes. The scope
openidtriggers the OIDC flow. Add additional scopes for your applications here.
- Scroll down to the Authentication section and observe that the pre-defined authentication mechanism is Authentication URL.
Click the Assemble tab. You will notice several policies that control the generation of the JWT for OIDC flows.
You must customize the
jwt-generatepolicies in accordance with your OIDC configuration; for example, to provide custom claims and other JWT information. For more information, see Generate JWT (jwt-generate).
- In the navigation pane, click Paths to display the paths that have been defined for the API.
- Modify the OAuth 2 OIDC Provider API in accordance with the guidance in step 5.
- Click the Save icon to save your changes.
For any APIs that you want to secure with OIDC, complete the following steps:
- Open the Design view for the API.
- Navigate to the Security Definitions section.
- Click the Add Security Definition icon and then click OAuth.
- Scroll down to your newly created OAuth security definition.
- Configure your OAuth definition as required, ensuring that you define a scope called openid, to match the scope that is defined in the pre-supplied sample OAuth Provider API.
- In the Security section, select the check box for your OAuth security definition, and ensure that the openid scope check box alongside it is also selected.
- Click the Save icon to save your changes.
- Create a Product, add your APIs and the customized OAuth Provider API to the Product, and include them in a Plan in the Product; for details, see Creating a Product.
- Stage the Product to your chosen Catalog; for details, see one or other of the following topics depending on whether you are working in IBM Cloud or in your own on-premises IBM API Connect for IBM Cloud deployment:
- Publish the Product; for details, see one or other of the following topics depending on whether you are working in IBM Cloud or in your own on-premises IBM API Connect for IBM Cloud deployment:
Test the APIs by using an environment capable of sending HTTP requests and receiving HTTP responses. The following commands test the APIs by using the
curlcommand in a command line interface. The commands here are for testing the OIDC Hybrid Flow; for testing other OIDC flows, you can use the same commands that you would use for the corresponding OAuth flows, but make sure that you include the
openidscope.Note: To test the APIs, you must have an account on the Developer Portal. You must also have created an application that you have then used to subscribe to the Plan that contains the APIs that you want to test. For more information, see Registering an application and Signing up to use an API. You need to make a note of your Client ID and Client Secret so you can run the following commands.
Log in and provide consent to the OAuth application. On successful completion, the OAuth application returns an authorization code and an ID token. The ID token is a JWT token that provides a set of claims.
Replace Authorization_Endpoint_URL, App_Scopes, Client_ID, Redirect_URI, and base64_encoded_username:password with the appropriate values. App_Scopes is a space-separated list of any additional scopes that you defined when you configured the OAuth Provider API.
curl -X GET \ 'Authorization_Endpoint_URL?scope=openid%20App_Scopes&response_type=id_token%20code&client_id=Client_ID&redirect_uri=Redirect_URI' \ -H 'authorization: Basic base64_encoded_username:password' \ -H 'content-type: application/text' \For example:
curl -X GET \ 'https://myhost.com:1234/myorg/mycatalog/oauth-end/oauth2/authorize?scope=openid%20profile%20email&response_type=id_token%20code&client_id=51dfaed9-9d07-46fc-83a6-52c09735a4a0&redirect_uri=https://example.com/redirect' \ -H 'authorization: Basic c8Bpb156c3Bvd24=' \ -H 'content-type: application/text' \
Exchange the authorization code for an access token.
Replace Token_Endpoint_URL, Redirect_URI, Client_ID, Client_Secret, and Authorization_Code with the appropriate values.
curl -X POST \ Token_Endpoint_URL \ -H 'content-type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code&redirect_uri=Redirect_URI&client_id=Client_ID&client_secret=Client_Secret&code=Authorization_CodeFor example:
curl -X POST \ https://myhost.com:1234/myorg/mycatalog/oauth-end/oauth2/token \ -H 'content-type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code&redirect_uri=https://example.com/redirect&client_id=51dfaed9-9d07-46fc-83a6-52c09735a4a0&client_secret=tW2cJ0cD0nY1qE6eH3yP8wQ2nT3eM5eV3cI1vU1qI6xN7fL7eS&code=AAL8k4uaJj3PCi7L026rR1BheJkzWKzR7vWgWvo--DBqYRVckkwcL
Use the access token to invoke the API.
Replace API_URL, Access_Token, Client_ID, and Client_Secret with the appropriate values.
curl -X GET \ 'API_URL' \ -H 'authorization: Bearer Access_Token' \ -H 'x-ibm-client-id: Client_ID \ -H 'x-ibm-client-secret: Client_Secret'For example:
curl -X GET \ 'https://myhost.com:1234/myorg/mycatalog/current?zipcode=90210' \ -H 'authorization: Bearer AAEHZGVmYXVsdIX4lOcqAfmg3xnrSMGmiqTLPhcQqFluuLdkWqxsaxudVMSBGBFY4KKdTa8NP7S3tJGi8K1vpDSam86j6W1Feaa-l5VnuKOMETEQTNJNiwVXJl3eUNwDfw67pwpP0dg6e_VcUA1VnjnzDiAHVQyHKm8' \ -H 'x-ibm-client-id: 51dfaed9-9d07-46fc-83a6-52c09735a4a0 \ -H 'x-ibm-client-secret: tW2cJ0cD0nY1qE6eH3yP8wQ2nT3eM5eV3cI1vU1qI6xN7fL7eS&code=AAL8k4uaJj3PCi7L026rR1BheJkzWKzR7vWgWvo--DBqYRVckkwcL'
- Log in and provide consent to the OAuth application. On successful completion, the OAuth application returns an authorization code and an ID token. The ID token is a JWT token that provides a set of claims.