Package com.ibm.websphere.security.oauth20.store

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>

  2. Registering with a user feature

    3. 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 Details

    • create

      void create(OAuthClient oauthClient) throws OAuthStoreException
      Creates an OAuthClient entry in the store.
      Parameters:
      oauthClient - the OAuthClient object representing the client to create in the store
      Throws:
      OAuthStoreException - if the store is not able to create the OAuthClient entry

    • create

      void create(OAuthToken oauthToken) throws OAuthStoreException
      Creates an OAuthToken entry in the store.
      Parameters:
      oauthToken - the OAuthToken object representing the token to create in the store
      Throws:
      OAuthStoreException - if the store is not able to create the OAuthToken entry

    • create

      void create(OAuthConsent oauthConsent) throws OAuthStoreException
      Creates an OAuthConsent entry in the store.
      Parameters:
      oauthConsent - the OAuthConsent object representing the consent to create in the store
      Throws:
      OAuthStoreException - if the store is not able to create the OAuthConsent entry

    • readClient

      OAuthClient readClient(String providerId, 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

      Collection<OAuthClient> readAllClients(String providerId, 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(String providerId, 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

      Collection<OAuthToken> readAllTokens(String providerId, 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(String providerId, String username, 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(String providerId, String username, String clientId, 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

    • update

      void update(OAuthClient oauthClient) throws OAuthStoreException
      Updates an OAuthClient entry in the store. If the entry does not exist, this operation will no-op.
      Parameters:
      oauthClient - the OAuthClient object representing the client to update in the store
      Throws:
      OAuthStoreException - if the store is not able to update the OAuthClient entry

    • update

      void update(OAuthToken oauthToken) throws OAuthStoreException
      Updates an OAuthToken entry in the store. If the entry does not exist, this operation will no-op.
      Parameters:
      oauthToken - the OAuthToken object representing the token to update in the store
      Throws:
      OAuthStoreException - if the store is not able to update the OAuthToken entry

    • update

      void update(OAuthConsent oauthConsent) throws OAuthStoreException
      Updates an OAuthConsent entry in the store. If the entry does not exist, this operation will no-op.
      Parameters:
      oauthConsent - the OAuthConsent object representing the consent to update in the store
      Throws:
      OAuthStoreException - if the store is not able to update the OAuthConsent entry

    • deleteClient

      void deleteClient(String providerId, 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(String providerId, 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(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(String providerId, String username, String clientId, 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(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