OpenID authentication for REST-based client workload submission

Body

IBM Spectrum Symphony’s SYMREST service is a RESTful server, which provides a RESTful API wrapper to submit workload and retrieve results from an IBM Spectrum Symphony client. It serves as a proxy server between the RESTful API client and your IBM Spectrum Symphony cluster to create client sessions and submit workload to an application in the cluster. To take advantage of SYMREST, you - the user - must pass authentication before you use the RESTful API. By default, SYMREST uses EGO authentication, which requires EGO credentials in the HTTP authentication header. Alternatively, in a Linux environment, you can enable SYMREST for single sign-on authentication through OpenID. IBM Spectrum Symphony supports OpenID Connect 1.0.

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows API clients to verify the identity of the end-user based on authentication by an authorization server. It also allows clients to obtain basic profile information about the end-user in an interoperable and REST-like manner. For more information about OpenID, refer to OpenID documentation.

When OpenID authentication is enabled, the SYMREST service relies on the EGO service OpenIdClient to communicate with the OpenID identity provider (IdP). This blog provides instructions on how to configure OpenID authentication for the SYMREST service and how to configure your IdP for the OpenIdClient service. All REST clients and IdPs that follow the OpenID connect 1.0 specification should work with the SYMREST and OpenIdClient services. In this post, we will see how to use Google’s OpenID Identity Provider as the SYMREST IdP. Google Chrome, Postman, and Postman interceptor are used as the RESTful client (Postman Interceptor sends requests that use browser cookies through the Postman app).

Prerequisites

Before configuring SYMREST and OpenIdClient, you must take care of several OpenID-related tasks:

1. Prepare a developer account from your IdP. For Google’s OpenID IDP, you need a Google account.
2. Register your OpenID client to your IdP and obtain the OpenID credentials. For Google’s OpenID IdP, you can acquire the credentials from the Google Developers Console (see documentation here). The redirect URL should use the host name and port of the OpenIdClient service, along with ‘/login’ in the path.

3. If the IdP uses HTTPS, you must acquire all CA certificates in the IdP’s certificate chain. For Google’s OpenID IDP, acquire Google’s CA certificate and GeoTrust’s CA certificate.

4. Prepare a script that will translate your IdP’s email to your EGO username and password. It must take your OpenID user email ID as input and provide the corresponding EGO user ID as output in the format egoUsername:egoPassword (for example, Admin:Admin).

Configuring OpenID authentication:

1. Configure symrest.json (available in the $EGO_CONFDIR/../../soam/profiles/conf directory) to enable OpenID authentication.

NOTE: By default, the OpenIdClient service enables HTTPS and uses the serverKeyStore.jks keystore in the $EGO_TOP/wlp/usr/shared/resources/security/ directory as the server keystore file, which is signed by cacert.pem.

2. Modify OpenIdClientConf.xml (available in the $EGO_CONFDIR/../../soam/profiles/conf directory) to use Google’s OpenID IdP as SYMREST’s IdP. The redirectUri field must be the same URL registered to your IDP.

3. Import Google’s CA certificate and GeoTrust’s CA certificate to the keystore used by OpenIdClient.

Restart the SYMREST and OpenIdClient services.

That’s it, you have successfully configured SYMREST to use Google’s IdP for OpenID authentication. Next, we will see how to access the RESTful APIs via Google Chrome, Postman, and Postman Interceptor.

Authenticating with OpenID and submitting workload

1. Let’s use Google Chrome to call the RESTful API to log in to your IdP. You must log in to the IDP first; otherwise SYMREST will report an authentication error, as shown in the following screenshot:

1. From your Chrome browser, access the URL https://host:port/platform/rest/symrest/v1/auth/loginIDP (for example, https://hyyvm1.eng.example.com:8050/platform/rest/symrest/v1/auth/login…), which will redirect you to Google’s login page.

2. Enter your email and password.

You should see a message that the user was successfully logged in.

2. Once you log in to the IDP successfully, the next steps are identical to EGO authentication.

2. Use Postman to call the RESTful API to log in to SYMREST, to acquire the csrf token for future use. You must provide this csrf token for next steps, otherwise SYMREST will not know who you are and whether you are logged in.

3. Use Postman to call the RESTful API to create a session. Specify the clusterId, applicationName, and csrftoken parameters in the request URL, and the session definition JSON file in the body; for example:

4. Use Postman to call the RESTful API to submit a task. Specify the clusterId, applicationName, sessionId, and csrftoken parameters in the request URL, and task input JSON files in the body, for example:

5. Use Postman to call the RESTful API to retrieve the task. Specify the clusterId, applicationName, sessionId, and csrftoken parameters in the request URL, and task output format JSON files in the body, for example:

6. Use Postman to call the RESTful API to delete the session. Specify the clusterId, applicationName, sessionId, and csrftoken parameters in the request URL, for example:

And there you have it: the workflow to submit workload from your RESTful API client. For more information, check out SYMREST topics in the IBM Knowledge Center.

Next steps: Talk to us!

We’d love to hear from you. If you’ve got comments or questions, add a comment below. You can also start a topic in our IBM Spectrum Symphony forum.