com.ibm.websphere.security.oidc.util

Class OauthClientHelper



  • public class OauthClientHelper
    extends OidcClientHelper

    This API has utility methods for interacting with the OpenID Connect (OIDC) Relying Party (RP) TAI.

    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 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
    • 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 OIDC session 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 OIDC session data.

        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 OIDC session data
        • 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 OIDC session 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 OIDC session data.

        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 OIDC session data
        • 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 a cached 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 OIDC SessionData 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 OIDC SessionData 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 9.0