com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Configuring a Third-Party Key Manager

Owned by Former user (Deleted)
Last updated: Nov 22, 2016 by Former user (Deleted)
5 min read

The Key Manager handles all clients, security and access token-related operations. In a typical API Manager production deployment, different components talk to the Key Manager component for achieving different tasks. The API Gateway connects with the Key Manager to check the validity of OAuth tokens, subscriptions and API invocations. When a subscriber generates an access token to the application using the API Store, the Store makes a call to the API Gateway, which in turn connects with the Key Manager to create an OAuth App and obtain an access token. Similarly, to validate a token, the API Gateway calls the Key Manager, which fetches and validates the token details from the database. For more information, see Key Manager.

The Key Manager decouples OAuth client and access token management from the rest of its operations, so that you can plug in a third-party OAuth provider for managing OAuth clients and access tokens. Let's see what basic steps to follow when writing a Key Manager implementation that acts as the bridge between a third-party OAuth provider and the API Manager.

In this guide, we use the Surf OAuth Authorization Server for managing OAuth clients and tokens required by the API Manager. We have a sample client implementation that consumes APIs exposed by Surf OAuth.

Starting the authorization server

  1. Download the binary located here and deploy it in a tomcat server. Alternatively, you can build the OAuth Server from scratch and start the server by issuing the  mvn jetty:run command in the api-authorization-server-war folder. 

    Tip: We have done the following changes to the Web application you just downloaded:

    • apis.application.properties file is copied to the classpath.
    • All the URLs starting with localhost are replaced by the loop back IP (127.0.0.1)
    • org.surfnet.oaaas.noop.NoopAuthenticator authenticator is set as the default authenticator.
    • Token expiry time is increased to 99999 seconds. This ensures that the tokens issued for the Web client lasts several months.

  2. Move the Web application to the ROOT context to ensure that the Surf Oauth Web applications works on Tomcat.

    rm -rf tomcat7/webapps/ROOT
mv tomcat7/webapps/surf-oauth tomcat7/webapps/ROOT
  3. Access http://127.0.0.1:8080/ to see the following page:
    The server is now up and running. Next, let's create a Resource Server and an OAuth Client.
  4. In Surf OAuth UI, click the Resource Servers link where all the OAuth clients are grouped together, and register a resource server representing WSO2 API Manager. Also, add two scopes named test and scope1. You will use them when creating clients.
    The front end is now registered as a distinct client with the authorization server. 
  5. Click the Access Token link and note all the tokens issued for the Web client. These tokens are obtained at the time you log in, by a Javascript client running on the browser. The same token is then used for subsequent operations.
  6. Pick an active access token from the above list. You use it to create clients through the API Manager. 
  7. Get a registration endpoint to register the client with. As Surf OAuth doesn’t support a spec-compliant client registration yet, you can use an endpoint with similar capabilities. For example, you can enable Developer Tools in Google Chrome to see the URL and the request being sent as shown below:

Configuring the API Manager

  1. Build the demo.client available at https://github.com/jaadds/surf-oauth-demo.git and copy the built JAR to <KM_HOME>/repository/components/lib folder. Note that <KM_HOME> is the API Manager distribution folder where the Key Manager is set up.

  2. Uncomment the <APIKeyManager> element in <KM_HOME>/repository/conf/api-manager.xml file and change the values according to your third-party implementation.

    Tip: Be sure to replace the <RegistrationEndpoint> and <AccessToken> with the client registration endpoint and the access token you obtained earlier in step 7 and 6. ConsumerKey and Secret should be that of the created Resource Server. Also change the <hostname> in the <IntrospectionURL> accordingly.

    <APIKeyManager>
       <KeyManagerClientImpl>nl.surfnet.demo.SurfOAuthClient</KeyManagerClientImpl>
        <Configuration>    
            <RegistrationEndpoint><Give the client registration endpoint you got in step 7></RegistrationEndpoint>
            <AccessToken><Give the access token you got in step 6></AccessToken>
            <IntrospectionURL>http://<hostname>:port/v1/tokeninfo</IntrospectionURL>
            <ConsumerKey>xxx</ConsumerKey>
            <ConsumerSecret>xxx</ConsumerSecret>
        </Configuration>
</APIKeyManager>

    Tip: See the WSO2 default Key Manager implementation for a sample Key Manager implementation.

Running the sample

You have connected the API Manager with a third-part authorization server. Let's see how the API Manger creates OAuth clients at Surf OAuth when applications are registered in the API Store. In this guide, we use the Published APIs to test invoke this process.

  1. Start the API Manager.

  2. Log in to the API Store and create an application.

    curl -k -X POST -c cookies https://localhost:9443/store/site/blocks/user/login/ajax/login.jag -d 'action=login&username=admin&password=admin'
curl -k -X POST -b cookies https://localhost:9443/store/site/blocks/application/application-add/ajax/application-add.jag -d 'action=addApplication&application=SurfClientApp&tier=Unlimited&description=&callbackUrl='

  3. Register an OAuth client of type PRODUCTION the authorization server. Note that you are sending the specific parameters required by the OAuth Server in JSON.

    curl -k -X POST -b cookies https://localhost:9443/store/site/blocks/subscription/subscription-add/ajax/subscription-add.jag -d 'action=generateApplicationKey&application=SurfClientApp&authorizedDomains=ALL&keytype=PRODUCTION&validityTime=3600&jsonParams={"scopes":["test"],"contactName":"John Doe","contactEmail":"john@doe.com"}'
  4. Go to the Client Applications link in the Surf OAuth UI and note the newly created client listed there.
    You have now created an application and registered an OAuth Client corresponding to it. Let’s see how to validate tokens by subscribing to a SurfClient application and obtaining a token.
  5. Log in to the API Publisher and deploy the sample API (CalculatorrAPI) if you haven't done so already.

  6. Assuming you still have the OAuth client created earlier, subscribe to this API as follows:

    curl -k -X POST -b cookies https://localhost:9443/store/site/blocks/subscription/subscription-add/ajax/subscription-add.jag -d 'action=addAPISubscription&name=CalculatorAPI&version=1.0&provider=admin&tier=Unlimited&applicationName=SurfClientApp'

    Let's obtain a token from the OAuth Provider.

  7. Go to the Edit view of the OAuth client and make sure the client_credentials grant type is enabled, and a token expiration time is specified.

  8. Obtain a token. Replace <ConsumerKey:ConsumerSecret> with the Base64 encoded ConsumerKey:ConsumerSecret of the client application you just created.

    curl -k -d "grant_type=client_credentials&scope=test" -H "Authorization: Basic <ConsumerKey:ConsumerSecret>" -H "Content-Type: application/x-www-form-urlencoded" http://localhost:8080/v1/token

  9. Invoke the API using it the token obtained.

    curl -k -H "Authorization:Bearer e17993f5-4479-432f-a058-790340963350" "http://localhost:8280/calc/1.0/add?x=2&y=4"
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.