Interface OAuthStore


  • public interface OAuthStore
    Interface for storing and accessing OAuth artifacts, such as clients, tokens, and consents, that are necessary for an OAuth flow. The implementation is responsible for securing the data at motion and rest.

    Implementing classes are required to define a zero-argument constructor so that they can be instantiated during loading.

    To make a OAuthStore implementation available to Liberty as an OSGi service there are two options.

    1. Basic Extensions using Liberty Libraries (BELL)
    2. The BELL feature uses the Java ServiceLoader facility to load an OSGi service from a library. Your JAR file must contain both the OAuthStore implementation class and the provider-configuration file. The following list shows the files that might go into a JAR file:

       myLibrary.jar
       -------------
       -- com/acme/CustomOAuthStore1.class
       -- com/acme/CustomOAuthStore2.class
       -- META-INF/services/com.ibm.websphere.security.oauth20.store.OAuthStore
       
      The provider-configuration file lists all the OAuthStore implementations to be provided as an OSGi service. For example, for myLibrary.jar, the META-INF/services/com.ibm.websphere.security.oauth20.store.OAuthStore provider-configuration file has a list of services, with each service on its own line. It *must* also specify the ID for each instance by inserting a comment line prior to each implementing class that contains a key value pair where the key is 'oauth.store.id' and the value is a unique ID that can be used to reference the instance from a OAuth provider in the server.xml.
       # oauth.store.id=customOAuthStore1
       com.acme.CustomOAuthStore1
      
       # oauth.store.id=customOAuthStore2
       com.acme.CustomOAuthStore2
       
      Once the JAR has been packaged, update the server.xml configuration to include the "bells-1.0" feature, the library that points to the JAR and the BELL configuration that points to the library. Finally, associate the OAuth provider to an OAuthStore implementation by adding a 'customStore' element to the 'oauthProvider' element and setting the 'storeId' attribute to the value of the 'oauth.store.id' of the implementation of the OAuthStore to use.

      Below is an example of associating 'customOAuthStore1' to an OAuth provider using the BELL feature.

       <server>
          <featureManager>
             <feature>oauth-2.0</feature>
             <feature>bells-1.0</feature>
          </featureManager>
      
          <!--
             Create a library for the JAR file that contains
             the OAuthStore implementation.
          -->
          <library id="mylibrary">
             <file name="${shared.resource.dir}/libs/myLibrary.jar">
          </library>
      
          <!-- Load the library in a BELL. -->
          <bell libraryRef="mylibrary" />
      
          <!-- Configure the OAuth provider with the custom OAuthStore implementation. -->
          <oauthProvider ...>
              <customStore storeId="customOAuthStore1" />
          </oauthProvider>
       </server>
       

    3. Registering with a user feature
    4. You can create a new OSGi service that implements the OAuthStore in a user feature. The service *must* define the property 'oauth.store.id' with a unique ID that can be used to reference the implementation from a OAuth provider in the server.xml. An example component XML file defining the component service might look like this:

       OSGI-INF/com.acme.CustomOAuthStore1.xml
       ---------------------------------------
       <component name="CustomOAuthStore1">
          <implementation class="com.acme.CustomOAuthStore1"/>
          <service>
             <provide interface="com.ibm.websphere.security.oauth20.store.OAuthStore"/>
          </service>
          <property name="service.vendor" type="String" value="ACME"/>
          <property name="oauth.store.id" type="String" value="customOAuthStore1"/>
       </component>
       

      When the user feature has been installed in Liberty, add the user feature to the feature list in the server.xml configuration file. Finally, associate the OAuth provider to an OAuthStore implementation by adding a 'customStore' element to the 'oauthProvider' element and setting the 'storeId' attribute to the value of the 'oauth.store.id' of the implementation of the OAuthStore to use.

      Below is an example of associating 'customOAuthStore1' to an OAuth provider using a user feature.

       <server>
          <featureManager>
             <feature>oauth-2.0</feature>
             <feature>user:myFeature-1.0</feature>
          </featureManager>
      
          <!-- Configure the OAuth provider with the custom OAuthStore. -->
          <oauthProvider ...>
             <customStore storeId="customOAuthStore1" />
          </oauthProvider>
       </server>
       
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      int countTokens​(java.lang.String providerId, java.lang.String username, java.lang.String clientId)
      Counts the OAuthToken entries matching the given providerId, username, and clientId arguments in the store.
      void create​(OAuthClient oauthClient)
      Creates an OAuthClient entry in the store.
      void create​(OAuthConsent oauthConsent)
      Creates an OAuthConsent entry in the store.
      void create​(OAuthToken oauthToken)
      Creates an OAuthToken entry in the store.
      void deleteClient​(java.lang.String providerId, java.lang.String clientId)
      Deletes an OAuthClient entry matching the providerId and clientId arguments from the store.
      void deleteConsent​(java.lang.String providerId, java.lang.String username, java.lang.String clientId, java.lang.String resource)
      Deletes an OAuthConsent entry matching the providerId, username, and clientId arguments from the store.
      void deleteConsents​(java.lang.String providerId, long timestamp)
      Deletes the OAuthConsent entries for the providerId from the store whose expiration fields are less than the given timestamp argument.
      void deleteToken​(java.lang.String providerId, java.lang.String lookupKey)
      Deletes an OAuthToken entry matching the providerId and lookupKey arguments from the store.
      void deleteTokens​(java.lang.String providerId, long timestamp)
      Deletes the OAuthToken entries for the providerId from the store whose expiration fields are less than the given timestamp argument.
      java.util.Collection<OAuthClient> readAllClients​(java.lang.String providerId, java.lang.String attribute)
      Reads all the OAuthClient entries matching the given providerId and attribute arguments from the store.
      java.util.Collection<OAuthToken> readAllTokens​(java.lang.String providerId, java.lang.String username)
      Reads all the OAuthToken entries matching the given providerId and username arguments from the store.
      OAuthClient readClient​(java.lang.String providerId, java.lang.String clientId)
      Reads the OAuthClient entry matching the given providerId and clientId arguments from the store.
      OAuthConsent readConsent​(java.lang.String providerId, java.lang.String username, java.lang.String clientId, java.lang.String resource)
      Reads the OAuthConsent entry matching the given providerId, username, clientId, and resource arguments from the store.
      OAuthToken readToken​(java.lang.String providerId, java.lang.String lookupKey)
      Reads the OAuthToken entry matching the given the providerId and lookupKey arguments from the store.
      void update​(OAuthClient oauthClient)
      Updates an OAuthClient entry in the store.
      void update​(OAuthConsent oauthConsent)
      Updates an OAuthConsent entry in the store.
      void update​(OAuthToken oauthToken)
      Updates an OAuthToken entry in the store.
    • Method Detail

      • readClient

        OAuthClient readClient​(java.lang.String providerId,
                               java.lang.String clientId)
                        throws OAuthStoreException
        Reads the OAuthClient entry matching the given providerId and clientId arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider the client is registered with
        clientId - the id of the client entry to find in the store
        Returns:
        the OAuthClient entry or null if no matching entry exists
        Throws:
        OAuthStoreException - if the store is not able to read an OAuthClient entry
      • readAllClients

        java.util.Collection<OAuthClient> readAllClients​(java.lang.String providerId,
                                                         java.lang.String attribute)
                                                  throws OAuthStoreException
        Reads all the OAuthClient entries matching the given providerId and attribute arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider the client is registered with
        attribute - an attribute of the client to match when reading the entry from the underlying store. If null, the method should return all clients for the specified provider.
        Returns:
        the collection of OAuthClient entries or null if no matching entries exist
        Throws:
        OAuthStoreException - if the store is not able to read the OAuthClient entries
      • readToken

        OAuthToken readToken​(java.lang.String providerId,
                             java.lang.String lookupKey)
                      throws OAuthStoreException
        Reads the OAuthToken entry matching the given the providerId and lookupKey arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider that issued the token
        lookupKey - the lookup key of the token entry to find in the store
        Returns:
        the OAuthToken entry or null if no matching entry exists
        Throws:
        OAuthStoreException - if the store is not able to read an OAuthToken entry
      • readAllTokens

        java.util.Collection<OAuthToken> readAllTokens​(java.lang.String providerId,
                                                       java.lang.String username)
                                                throws OAuthStoreException
        Reads all the OAuthToken entries matching the given providerId and username arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider that issued the tokens
        username - the user the tokens were issued for
        Returns:
        the OAuthToken entries or null if no matching entries exist
        Throws:
        OAuthStoreException - if the store is not able to read the OAuthToken entries
      • countTokens

        int countTokens​(java.lang.String providerId,
                        java.lang.String username,
                        java.lang.String clientId)
                 throws OAuthStoreException
        Counts the OAuthToken entries matching the given providerId, username, and clientId arguments in the store.
        Parameters:
        providerId - the id of the OAuth provider that issued the tokens
        username - the user the tokens were issued for
        clientId - the id of the client the tokens were issued to
        Returns:
        the number of tokens the user was issued for the client with the given clientId from the provider with the given providerId
        Throws:
        OAuthStoreException - if the store is not able to count the OAuthToken entries
      • readConsent

        OAuthConsent readConsent​(java.lang.String providerId,
                                 java.lang.String username,
                                 java.lang.String clientId,
                                 java.lang.String resource)
                          throws OAuthStoreException
        Reads the OAuthConsent entry matching the given providerId, username, clientId, and resource arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider from which consent was given
        userame - the user that gave consent
        clientId - the id of the client granted consent to access the resource
        resource - the resource the client was granted consent to
        Returns:
        the OAuthConsent entries or null if no matching entry exists
        Throws:
        OAuthStoreException - if the store is not able to read an OAuthConsent entry
      • deleteClient

        void deleteClient​(java.lang.String providerId,
                          java.lang.String clientId)
                   throws OAuthStoreException
        Deletes an OAuthClient entry matching the providerId and clientId arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider the client is registered with
        clientId - the id of the client entry to delete from the store
        Throws:
        OAuthStoreException - if the store is not able to delete the OAuthClient entry
      • deleteToken

        void deleteToken​(java.lang.String providerId,
                         java.lang.String lookupKey)
                  throws OAuthStoreException
        Deletes an OAuthToken entry matching the providerId and lookupKey arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider that issued the token
        lookupKey - the lookup key of the token entry to delete from the store
        Throws:
        OAuthStoreException - if the store is not able to delete the OAuthToken entry
      • deleteTokens

        void deleteTokens​(java.lang.String providerId,
                          long timestamp)
                   throws OAuthStoreException
        Deletes the OAuthToken entries for the providerId from the store whose expiration fields are less than the given timestamp argument.
        Parameters:
        providerId - the id of the OAuth provider that issued the token
        timestamp - the time in milliseconds since the epoch to compare the token entry expiration with to delete the entry from the store
        Throws:
        OAuthStoreException - if the store is not able to delete the OAuthToken entries
      • deleteConsent

        void deleteConsent​(java.lang.String providerId,
                           java.lang.String username,
                           java.lang.String clientId,
                           java.lang.String resource)
                    throws OAuthStoreException
        Deletes an OAuthConsent entry matching the providerId, username, and clientId arguments from the store.
        Parameters:
        providerId - the id of the OAuth provider from which consent was given
        username - the user that gave consent
        clientId - the id of the client for which to delete the user consent entry from the store
        resource - the resource the client was granted consent to
        Throws:
        OAuthStoreException - if the store is not able to delete the OAuthConsent entry
      • deleteConsents

        void deleteConsents​(java.lang.String providerId,
                            long timestamp)
                     throws OAuthStoreException
        Deletes the OAuthConsent entries for the providerId from the store whose expiration fields are less than the given timestamp argument.
        Parameters:
        providerId - the id of the OAuth provider from which consent was given
        timestamp - the time in milliseconds since the epoch to compare the consent entry expiration with to delete the entry from the store
        Throws:
        OAuthStoreException - if the store is not able to delete the OAuthConsent entries