Class: OAuth2::Strategy::Assertion — Documentation by YARD 0.9.45

# Class: OAuth2::Strategy::Assertion

Inherits:
  Base
  - Object
  - Base
  - OAuth2::Strategy::Assertion
  show all

Defined in:
  lib/oauth2/strategy/assertion.rb

## Overview

The Client Assertion Strategy

Sample usage:
client = OAuth2::Client.new(client_id, client_secret,
:site => ‘http://localhost:8080’,
:auth_scheme => :request_body)

claim_set = {
:iss => “http://localhost:3001”,
:aud => “http://localhost:8080/oauth2/token”,
:sub => “me@example.com”,
:exp => Time.now.utc.to_i + 3600,
}

encoding = {
:algorithm => ‘HS256’,
:key => ‘secret_key’,
}

access = client.assertion.get_token(claim_set, encoding)
access.token # actual access_token string
access.get(“/api/stuff”) # making api calls with access token in header

See Also:

- https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-10#section-4.1.3

## Instance Method Summary collapse

- #authorize_url ⇒ Object

  Not used for this strategy.

- #get_token(claims, encoding_opts, request_opts = {}, response_opts = {}) ⇒ Object

  Retrieve an access token given the specified client.

### Methods inherited from Base

#initialize

## Constructor Details

This class inherits a constructor from OAuth2::Strategy::Base

## Instance Method Details

### #authorize_url ⇒ `Object`

Not used for this strategy

Raises:

- (`NotImplementedError`)

    36
    37
    38
    # File 'lib/oauth2/strategy/assertion.rb', line 36

    def authorize_url
      raise(NotImplementedError, "The authorization endpoint is not used in this strategy")
    end

### #get_token(claims, encoding_opts, request_opts = {}, response_opts = {}) ⇒ `Object`

Retrieve an access token given the specified client.

For reading on JWT and claim keys:
@see https://github.com/jwt/ruby-jwt
@see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
@see https://datatracker.ietf.org/doc/html/rfc7523#section-3
@see https://www.iana.org/assignments/jwt/jwt.xhtml

There are many possible claim keys, and applications may ask for their own custom keys.
Some typically required ones:
:iss (issuer)
:aud (audience)
:sub (subject) – formerly :prn https://datatracker.ietf.org/doc/html/draft-ietf-oauth-json-web-token-06#appendix-F
:exp, (expiration time) – in seconds, e.g. Time.now.utc.to_i + 3600

Note that this method does not validate presence of those four claim keys indicated as required by RFC 7523.
There are endpoints that may not conform with this RFC, and this gem should still work for those use cases.

These two options are passed directly to `JWT.encode`. For supported encoding arguments:
@see https://github.com/jwt/ruby-jwt#algorithms-and-usage
@see https://datatracker.ietf.org/doc/html/rfc7518#section-3.1

The object type of `:key` may depend on the value of `:algorithm`. Sample arguments:
`get_token(claim_set, {:algorithm => 'HS256', :key => 'secret_key'})`
`get_token(claim_set, {:algorithm => 'RS256', :key => OpenSSL::PKCS12.new(File.read('my_key.p12'), 'not_secret')})`

Parameters:

- claims (`Hash`) —

  the hash representation of the claims that should be encoded as a JWT (JSON Web Token)

- encoding_opts (`Hash`) —

  a hash containing instructions on how the JWT should be encoded

- request_opts (`Hash`) (defaults to: `{}`) —

  options that will be used to assemble the request

- response_opts (`Hash`) (defaults to: `{}`) —

  this will be merged with the token response to create the AccessToken object
  @see the access_token_opts argument to Client#get_token

- algorithm (`Hash`) —

  a customizable set of options

- key (`Hash`) —

  a customizable set of options

Options Hash (`request_opts`):

- :scope (`String`) —

  the url parameter `scope` that may be required by some endpoints
  @see https://datatracker.ietf.org/doc/html/rfc7521#section-4.1

    79
    80
    81
    82
    83
    84
    # File 'lib/oauth2/strategy/assertion.rb', line 79

    def get_token(claims, encoding_opts, request_opts = {}, response_opts = {})
      assertion = build_assertion(claims, encoding_opts)
      params = build_request(assertion, request_opts)

      @client.get_token(params, response_opts)
    end