Skip to content

Configure WSO2 IS as a Key Manager

WSO2 API Manager supports multiple Key Managers. As a result, WSO2 API Manager is prepacked with an inbuilt resident Key Manager and it has the inbuilt capability of configuring WSO2 Identity Server (WSO2 IS) as a Key Manager.

Follow the steps given below to configure WSO2 IS as a Key Manager component:

Step 1 - Configure WSO2 IS

  1. Download and install the WSO2 Identity Server 6.0.0 or 6.1.0.

    If you downloaded the archive, extract it. <IS_HOME> refers to the root folder of the extracted WSO2 IS.

    Tip

    Refer to the Release Matrix for compatible product versions.

  2. Add following configurations in the <IS_HOME>/repository/conf/deployment.toml file.

    [[event_listener]]
id = "token_revocation"
type = "org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"
name = "org.wso2.is.notification.ApimOauthEventInterceptor"
order = 1
[event_listener.properties]
notification_endpoint = "https://localhost:9443/internal/data/v1/notify"
username = "${admin.username}"
password = "${admin.password}"
'header.X-WSO2-KEY-MANAGER' = "WSO2-IS"

[[resource.access_control]]
context = "(.)/keymanager-operations/user-info/claims(.)"
secure = true
http_method = "GET"
permissions = "/permission/admin/manage/identity/usermgt/list"
scopes = "internal_user_mgt_list"

[[resource.access_control]]
context = "(.*)/keymanager-operations/user-info/claims/generate"
secure = true
http_method = "POST"
permissions = "/permission/admin/manage/identity/usermgt/list"
scopes = "internal_user_mgt_list"

[[resource.access_control]]
context = "(.*)/keymanager-operations/dcr/register"
secure = true
http_method = "POST"
permissions = "/permission/admin/manage/identity/applicationmgt/create"
scopes = "internal_application_mgt_create"

[[resource.access_control]]
context = "(.*)/keymanager-operations/dcr/register(.*)"
secure = true
http_method = "GET"
permissions = "/permission/admin/manage/identity/applicationmgt/view"
scopes = "internal_application_mgt_view"

[[resource.access_control]]
context = "(.*)/keymanager-operations/dcr/register(.*)"
secure = true
http_method = "PUT"
permissions = "/permission/admin/manage/identity/applicationmgt/update"
scopes = "internal_application_mgt_update"

[[resource.access_control]]
context = "(.*)/keymanager-operations/dcr/register(.*)"
secure = true
http_method = "POST"
permissions = "/permission/admin/manage/identity/applicationmgt/update"
scopes = "internal_application_mgt_update"

[[resource.access_control]]
context = "(.*)/keymanager-operations/dcr/register(.*)"
secure = true
http_method = "DELETE"
permissions = "/permission/admin/manage/identity/applicationmgt/delete"
scopes = "internal_application_mgt_delete"

[tenant_context.rewrite]
custom_webapps = ["/keymanager-operations/"]

  3. Download the WSO2 IS Connector.

  4. Extract the distribution and copy the following JAR files to the <IS_HOME>/repository/components/dropins directory.

    • wso2is.key.manager.core-1.6.8.jar
    • wso2is.notification.event.handlers-1.6.8.jar

  5. Add keymanager-operations.war to the <IS_HOME>/repository/deployment/server/webapps directory.

  6. Start WSO2 Identity Server with a port offset. portOffset is required only if you are running both API-M and IS in the same JVM.

    sh wso2server.sh -DportOffset=1

Step 2 - Configure WSO2 API Manager

  1. Start WSO2 API Manager.

    <APIM_HOME> refers to the root folder of the extracted WSO2 APIM.

  2. Sign in to the Admin Portal.

    https://<hostname>:9443/admin

    https://localhost:9443/admin

  3. Click Key Managers.

  4. Click Add Key Manager to add the configuration related to a new Key Manager.

    Add new Key Manager

  5. Add the Key Manager configurations.

    The following table provides definitions for each configuration.

    Configuration Description Required or Not
    Name The name of the authorization server. Mandatory
    Display Name A name to display on the UI. Mandatory
    Description A brief description of the Key Manager. Optional
    Key Manager Type The type of the Key Manager to be selected.
    e.g., WSO2 Identity Server    		 Mandatory
    Well-known-url The well-known URL of the authorization server (Key Manager). Optional
    Issuer The issuer that consumes or validates access tokens
    e.g., https://localhost:9444/services    		 Optional
    Key Manager Endpoints
    Client Registration Endpoint

    The endpoint that verifies the identity and obtain profile information of the end-user based on the authentication performed by an authorization server.
    e.g., https://localhost:9444/keymanager-operations/dcr/register


    If you have set the following as a well known endpoint, you need to set the Client Registration Endpoint as https://localhost:9444/keymanager-operations/dcr/register

    1. https://localhost:9444/oauth2/oidcdiscovery/.well-known/openid-configuration
    2. https://localhost:9444/oauth2/token/.well-known/openid-configuration

    		 Optional if the well-known URI is provided.
    Introspection Endpoint

    The endpoint that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth Client.
    e.g., https://localhost:9444/oauth2/introspect

    		 Optional if the well-known URI is provided.
    Token Endpoint The endpoint that issues the access tokens.
    e.g., https://localhost:9444/oauth2/token    		 Optional
    Revoke Endpoint The endpoint that revokes the access tokens.
    e.g., https://localhost:9444/oauth2/revoke    		 Optional
    Userinfo Endpoint

    The endpoint that allows clients to verify the identity of the end-user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end-user.
    e.g., https://localhost:9444/oauth2/userinfo?schema=openid

    If you have set the following as a well known endpoint, you need to set the Userinfo Endpoint as https://localhost:9444/oauth2/userinfo?schema=openid

    1. https://localhost:9444/oauth2/oidcdiscovery/.well-known/openid-configuration
    2. https://localhost:9444/oauth2/token/.well-known/openid-configuration


    		 Optional
    Authorize Endpoint The endpoint used to obtain an authorization grant from the resource owner via the user-agent redirection.
    e.g., https://localhost:9444/oauth2/authorize    		 Optional
    Scope Management Endpoint The endpoint used to manage the scopes.
    e.g., https://wso2is.com:9444/api/identity/oauth2/v1.0/scopes    		 Mandatory
    Connector Configurations
    Username The username of an admin user who is authorized to connect to the authorization server. Mandatory
    Password The password corresponding to the latter mentioned admin user who is authorized to connect to the authorization server. Mandatory
    Claim URIs Provide the claim URIs for the consumer key and the scopes. Optional
    Consumer Key Claim URI The claim URI for the consumer key. Optional
    Scopes Claim URI The claim URI for the scopes. Optional
    Grant Types The supported grant types. Add multiple grant types by adding a grant type press Enter.
    e.g., refresh_token, password, client_credentials, authorization_code    		 Optional
    Certificates
    PEM Either copy and paste the certificate in PEM format or upload the PEM file. Optional
    JWKS The JSON Web Key Set (JWKS) endpoint is a read-only endpoint. This URL returns the Identity Server's public key set in JSON web key set format. This contains the signing key(s) the Relying Party (RP) uses to validate signatures from the Identity Server.
    e.g., https://localhost:9444/oauth2/jwks    		 Optional
    Advanced Configurations
    Token Generation This enables token generation via the authorization server. Mandatory
    Out Of Band Provisioning This enables the provisioning of Auth clients that have been created without the use of the Developer Portal, such as previously created Auth clients. Mandatory
    Oauth App Creation This enables the creation of Auth clients. Mandatory
    Token Validation Method The method used to validate the JWT signature. Optional
    Self Validate JWT The kid value is used to validate the JWT token signature. If the kid value is not present, gateway_certificate_alias will be used. Optional
    Use introspect The JWKS endpoint is used to validate the JWT token signature. Optional
    Token Handling Options This provides a way to validate the token for this particular authorization server. This is mandatory if the Token Validation Method is introspect
    REFERENCE The tokens that match a specific regular expression (regEx) are validated. e.g., [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12} Optional
    JWT The tokens that match a specific JWT are validated. Optional
    CUSTOM The token that match a custom pattern are validated. Optional
    Claim Mappings Local and remote claim mapping. Optional

You can also configure the WSO2 Identity Server as the identity provider. For more information on how to do this, see Configuring WSO2 Identity Server as an Identity Provider.