com.ibm.websphere.security.oidc.util

Class OauthClientHelper


  • public class OauthClientHelper
extends OidcClientHelper

    This API allows an application to use the OpenID Connect (OIDC) TAI to communicate with a previously configured OAuth provider.

    The OIDC TAI allows for both client_credentials and password grant types. The grant type is configured on the provider_<id>.grantType OIDC TAI custom property.. The tokens returned from the server are cached and the access token is refreshed if configured to do so.

    This API contains two sets of methods; one set that operates on the runAs subject and another that operates on a Subject that is passed into the method. If you are running the methods from a business application, the standard versions that use the runAs subject will suffice. However, if you are running the methods from a JAAS login module, there are conditions where the runAs subject may not be updated with the Oauth/OIDC data, but the JAAS Subject has. In this case, you would use the set of methods where you pass the Subject into the method.

    The OauthClientHelper class can be found in the following jars:

    • plugins/com.ibm.ws.security.oidc.client.jar
    • dev/was_public.jar

    Usage Notes:

    When you are operating from data on the runAs Subject, you may not know if the data was obtained with OAuth APIs or an OIDC login. Since the OAuth data occupies the same cache as the OIDC session data, the getValidAccessToken methods in both the OauthClientHelper and OidcClientHelper classes will operate on tokens cached either way.

    However, if you want to perform any operation that takes an access token as a parameter, the access token must be obtained with an OAuth method, not an OIDC login. For example, if you want to use OauthClientHelper.getValidAccessToken(String token), you must first obtain the token with one of the OauthClientHelper methods. For instance, OauthClientHelper.getPasswordGrantAccessToken().

    • Constructor Detail

      • OauthClientHelper

        public OauthClientHelper()

    • Method Detail

      • getValidAccessToken

        public static java.lang.String getValidAccessToken()
                                            throws java.lang.Exception

        Retrieve a valid access token based on the access token in the current runAs Subject

        A null value will be returned in the following instances:

        • Administrative security is not enabled.
        • Trust Association is not enabled.
        • The OIDC RP TAI is not configured and successfully initialized.
        • There is no access token on the runAs Subject.
        • There are any errors while attempting to obtain the OAuth data associated with the access token on the runAs Subject.
        • The access token on the runAs Subject has expired and there is no refresh token associated with the access token.
        • The access token on the runAs Subject has expired and any error occurs while attempting to refresh the token.
        • The access token on the runAs Subject has expired and any error occurs while updating the OAuth token cache.

        If the access token retrieved from the runAs subject has expired and is successfully refreshed, the following will be updated with the new access token:

        • Its associated OAuth token cache
        • The runAs Subject

        This method will only throw an exception if errors occur related to the initial processing of the runAs Subject. If an error occurs after information has been retrieved from the runAs Subject, an FFDC entry will be created, but the exception will not be emitted by this method and the method will return null in most cases. If the access token has been refreshed, but the runAs Subject cannot be updated, an FFDC will be emitted and the method will return the new access token.

        If there is a userinfoEndpointUrl configured for the access token, the user info will also be refreshed.

        Returns:
        JSON String representation of a valid access token or null if the conditions listed above are true.
        Throws:
        java.lang.Exception - if an error occurs either while obtaining the runAs Subject or accessing the private credentials.

      • getValidAccessToken

        public static java.lang.String getValidAccessToken(javax.security.auth.Subject subj)
                                            throws java.lang.Exception

        Retrieve a valid access token based on the access token in the input Subject.

        A null value will be returned in the following instances:

        • The input subject is null.
        • Administrative security is not enabled.
        • Trust Association is not enabled.
        • The OIDC RP TAI is not configured and successfully initialized.
        • There is no access token on the input Subject.
        • There are any errors while attempting to obtain the OAuth data associated with the access token on the input Subject.
        • The access token on the input Subject has expired and there is no refresh token associated with the access token.
        • The access token on the input Subject has expired and any error occurs while attempting to refresh the token.
        • The access token on the input Subject has expired and any error occurs while updating the OAuth token cache.

        If the access token retrieved from the input subject has expired and is successfully refreshed, the following will be updated with the new access token:

        • Its associated OAuth token cache/li>
        • The input Subject

        This method will only throw an exception if errors occur related to the initial processing of the input Subject. If an error occurs after information has been retrieved from the input Subject, an FFDC entry will be created, but the exception will not be emitted by this method and the method will return null in most cases. If the access token has been refreshed, but the input Subject cannot be updated, an FFDC will be emitted and the method will return the new access token.

        If there is a userinfoEndpointUrl configured for the access token, the user info will also be refreshed.

        Returns:
        JSON String representation of a valid access token or null if the conditions listed above are true.
        Throws:
        java.lang.Exception - if an error occurs when accessing the private credentials in the Subject.

      • getValidAccessToken

        public static java.lang.String getValidAccessToken(java.lang.String token)
                                            throws java.lang.Exception
        Retrieve a valid access token based on a cached OAuth access token . A null value will be returned in the following instances: * Trust Association is not enabled. * The OIDC RP TAI is not configured and successfully initialized. * There are any errors while attempting to obtain the OAuth data associated with the input token. * There is no refresh token associated with the input access token. * The input access token has expired and any error occurs while attempting to refresh the token. * The input access token has expired and any error occurs while updating the OAuth token cache. If the input access token has expired and is successfully refreshed, the following will be updated with the new access token: * It is associated OAuth data in the OAuth token cache
        Returns:
        A valid access token or null if the conditions listed above are true.
        Throws:
        java.lang.Exception - if an error occurs when accessing the private credentials in the Subject.

      • getClientCredentialsGrantAccessToken

        public static java.lang.String getClientCredentialsGrantAccessToken()
                                                             throws java.lang.Exception

        Retrieve an access token from the token endpoint using the client_credentials grant_type

        An exception will be emitted in the following instances:

        • Trust Association is not enabled.
        • There is no valid OIDC RP TAI configuration entry specifying grantType=client_credentials or grantType=all.
        • An error occurs while obtaining the access token from the token endpoint.
        • An access token is not received from the token endpoint.

        Returns:
        The access token retrieved from the server
        Throws:
        java.lang.Exception - if one of the error outlined above occurs

      • getPasswordGrantAccessToken

        public static java.lang.String getPasswordGrantAccessToken(java.lang.String username,
                                           java.lang.String password)
                                                    throws java.lang.Exception

        Retrieve an access token from the token endpoint using the password grant_type

        An exception will be emitted in the following instances:

        • Trust Association is not enabled.
        • There is no valid OIDC RP TAI configuration entry specifying grantType=password or grantType=all.
        • An error occurs while obtaining the access token from the token endpoint.
        • An access token is not received from the token endpoint.

        Returns:
        The access token retrieved from the server
        Throws:
        java.lang.Exception - if one of the error outlined above occurs

      • createSubjectForJaasLogin

        public static javax.security.auth.Subject createSubjectForJaasLogin(java.lang.String token)
                                                             throws java.lang.Exception

        Create a Subject based on an OAuth access token.

        This method can be used if you have obtained an OAuth token in a JAAS login module and want to create a Subject that the Oauth/OIDC APIs can use. It will contain the OIDC hashtable that has the access token, refresh token, etc. If userinfo was obtained during the process, the WSCREDENTIAL_SECURITYNAME will be set to the user name from the userinfo.

        An exception will be emitted in the following instances:

        • Trust Association is not enabled.
        • There is no valid OIDC RP TAI configuration entry specifying grantType=password or grantType=all.
        • An error occurs while obtaining the access token from the token endpoint.
        • An access token is not received from the token endpoint.

        The method will return null if the OAuth access token is not found in the OAuth token cache.

        This method will only create Subjects for OAuth tokens that were obtained with OAuth APIs.

        Returns:
        Subject based on the input OAuth access token
        Throws:
        java.lang.Exception - if one of the error outlined above occurs

      • createHashtableForJaasLogin

        public static java.util.Hashtable createHashtableForJaasLogin(java.lang.String token)
                                                       throws java.lang.Exception

        Create a Hashtable for use in a JAAS login based on an OAuth access token.

        This method can be used if you have obtained an OAuth token in a JAAS login module and want to create a Hashtable that the Oauth/OIDC APIs can use. This Hashtable is added to the Subject that you create. If userinfo was obtained during the process, the WSCREDENTIAL_SECURITYNAME will be set to the user name from the userinfo.

        An exception will be emitted in the following instances:

        • Trust Association is not enabled.
        • There is no valid OIDC RP TAI configuration entry specifying grantType=password or grantType=all.
        • An error occurs while obtaining the access token from the token endpoint.
        • An access token is not received from the token endpoint.

        The method will return null if the OAuth access token is not found in the OAuth token cache.

        Returns:
        OIDC Hashtable based on the input OAuth access token
        Throws:
        java.lang.Exception - if one of the error outlined above occurs

      • createHashtableForJaasLogin

        public static java.util.Hashtable createHashtableForJaasLogin(java.lang.String token,
                                              boolean allowTokenWithNoSessionData)
                                                       throws java.lang.Exception

        Create a Hashtable for use in a JAAS login based on an OAuth access token.

        This method can be used if you have obtained an OAuth token in a JAAS login module and want to create a Hashtable that the Oauth/OIDC APIs can use. This Hashtable is added to the Subject that you create. If userinfo was obtained during the process, the WSCREDENTIAL_SECURITYNAME will be set to the user name from the userinfo.

        An exception will be emitted in the following instances:

        • Trust Association is not enabled.
        • There is no valid OIDC RP TAI configuration entry specifying grantType=password or grantType=all.
        • An error occurs while obtaining the access token from the token endpoint.
        • An access token is not received from the token endpoint.

        set allowTokenWithNoSessionData to true if you want a Hashtable back even if no SessionData is found that corresponds to the token. In this case, only the token itself will be in the hashtable. If you put the Hashtable on a Subject, the Oauth/OIDC APIs will be able to retrieve it.

        Returns:
        OIDC Hashtable based on the input OAuth access token
        Throws:
        java.lang.Exception - if one of the error outlined above occurs
IBM WebSphere Application ServerTM
Release 8.5