Note: This repo is managed by the VA.gov Identity team. Please reference our main product page here for contact information and questions.

The SignInService Ruby client provides a simple and convenient way to interact with the SignInService API for handling OAuth flows.

Add gem to your Gemfile

gem 'sign_in_service', :git => 'git://github.com/department-of-veterans-affairs/sign-in-service-rb.git'

bundle install

Configure the SignInService client with your base URL, client ID, and authentication type in an initializer:

require 'sign_in_service'

SignInService::Client.configure do |config|
  config.base_url = 'https://your_sign_in_service_url'
  config.client_id = 'your_client_id'
  config.auth_type = :cookie # or :api
end

The SignInService client supports two authentication types: Cookie and API.

With Cookie authentication, tokens are returned in the Set-Cookie headers of the response. This approach is typically used in web applications where cookies can be stored and managed directly by the browser.

With API authentication, tokens are returned in the response body. This approach is typically used in non-web applications or scenarios where the application handles the tokens directly, such as mobile apps, desktop apps, or server-side scripts.

• Authorize - Initiate the OAuth flow
• Token - Exchange authorization code for session tokens

• Refresh - Refresh session tokens.
• Logout - Log out the user and revoke tokens.
• Revoke Token - Revoke a sessions tokens.
• Revoke All Sessions - Revoke all sessions associated with a user

SignInService::Sts.configure do |config|
  config.base_url = 'https://api.va.gov' # Sign-in service URL
  config.service_account_id = 'your_client_id'
  config.issuer = 'your_client_secret',
  config.scopes = ["https://api.va.gov/v0/some-path"]
  config.user_attributes = ['icn'] # optional
  config.private_key_path = 'path/to/private_key.pem'
end

Or create a new instance of the STS client with the configuration (overrides the global configuration):

sts_client = SignInService::Sts.new(
  base_url: 'https://api.va.gov',
  service_account_id: 'your_client_id',
  issuer: 'your_client_secret',
  scopes: ["https://api.va.gov/v0/some-path"],
  user_attributes: ['icn'], # optional
  private_key_path: 'path/to/private_key.pem'
)

When requesting a token you need to pass in a user_identifier to be used as the subject of the token. This can be an ICN, email, or any other unique identifier.

sts = SignInService::Sts.new(user_identifier: '1234567890') # And other configuration options not in the global configuration

token = sts.request_token