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.

Note: The following multivalued response types are supported:
  • code id_token
  • id_token code

Procedure

  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 Navigate to icon.
    The API Manager UI navigation pane opens. To pin the UI navigation pane, click the Pin menu icon The Pin menu icon..
  3. Click Drafts in the UI navigation pane, and then click APIs.
    The APIs tab opens.
  4. Import the pre-supplied sample OAuth Provider API as follows:
    1. Click Add > Import API from a file or URL.
    2. Click Or import from URL and in the URL field enter https://raw.githubusercontent.com/ibm-apiconnect/openid/master/oidc_1.0.0.yaml
    3. Click Import.
      The specified YAML file is imported, and the associated API definition, called OAuth 2 OIDC Provider, opens in the Design view.
  5. Click the OAuth 2 OIDC Provider API and examine the API as follows:
    1. 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/authorize and /oauth2/token. The path /oauth2/introspect lets you obtain information about the access token.

    2. In the navigation pane, click OAuth 2.

      The default grant types are supported, but of particular importance are the available scopes. The scope openid triggers the OIDC flow. Add additional scopes for your applications here.

    3. Scroll down to the Authentication section and observe that the pre-defined authentication mechanism is Authentication URL.

      You must change the settings in this section in accordance with the authentication mechanism that you are using; for more information, see the Authentication section in Creating an OAuth provider API.

    4. Click the Assemble tab. You will notice several policies that control the generation of the JWT for OIDC flows.

      You must customize the set-variable and jwt-generate policies in accordance with your OIDC configuration; for example, to provide custom claims and other JWT information. For more information, see Generate JWT (jwt-generate).

  6. Modify the OAuth 2 OIDC Provider API in accordance with the guidance in step 5.
  7. Click the Save icon The Save icon. to save your changes.
  8. For any APIs that you want to secure with OIDC, complete the following steps:
    1. Open the Design view for the API.
    2. Navigate to the Security Definitions section.
    3. Click the Add Security Definition icon The Add Security Definition icon and then click OAuth.
    4. Scroll down to your newly created OAuth security definition.
    5. 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.
    6. 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.
    7. Click the Save icon The Save icon. to save your changes.
  9. 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.
  10. 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:
  11. 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:
  12. 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 curl command 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 openid scope.
    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.
    1. 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.
      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' \
      
      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.
      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' \
      
    2. Exchange the authorization code for an access token.
      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_Code
      Replace Token_Endpoint_URL, Redirect_URI, Client_ID, Client_Secret, and Authorization_Code with the appropriate values.
      For 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
      
    3. Use the access token to invoke the API.
      curl -X GET \
        'API_URL' \
        -H 'authorization: Bearer Access_Token' \
        -H 'x-ibm-client-id: Client_ID \
        -H 'x-ibm-client-secret: Client_Secret'
      
      Replace API_URL, Access_Token, Client_ID, and Client_Secret with the appropriate values.
      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'