Identity and Auth

Identities, Identity Resolvers, Auth Schemes, Auth Resolvers, and Signers are components that are used to authenticate a request with a service. Smithy supports many authentication schemes using modeled authentication traits.

Below example showcases using httpApiKeyAuth trait:

@railsJson
@title("High Score Sample Rails Service")
@httpApiKeyAuth(name: "X-API-Key", in: "header")
service HighScoreService {
    version: "2021-02-15",
    resources: [HighScore]
}

Identity and Identity Resolver

Identities are classes that contain sensitive credentials used for authentication with the service, such as usernames, passwords, API keys, etc. Identities inherit from Hearth::Identities::Base.

Identity Resolvers are any class that responds to an identity(properties = {}) method. This method is responsible for returning an Identity. Hearth provides a Hearth::IdentityResolver class that wraps a Ruby proc to provide an Identity, as well as a Hearth::RefreshingIdentityResolver module for a refreshing Identity when it is near expiration.

An identity resolver Config option is generated for each Identity type that uses it. For example, if the service is modeled with @httpApiKeyAuth, there will be a :http_api_key_auth_identity_resolver config option.

identity_resolver = Hearth::IdentityResolver.new(proc do
  Hearth::Identities::HTTPAPIKey.new(key: 'my secret')
end)
# => #<Hearth::IdentityResolver ... >

client = HighScoreService::Client.new(
  endpoint: 'http://127.0.0.1:3000',
  http_api_key_identity_resolver: identity_resolver
)
# => #<HighScoreService::Client ... >

client.list_high_scores
# <Signs with API key>
# => #<Hearth::Output @data=... >

Auth Schemes and Auth Resolver

Auth Resolvers are any class that responds to resolve(params) where params is a Struct containing auth params. By default, auth params only contains the :operation_name however custom auth params can be added by the model and Java integrations. The Auth Resolver is responsible for returning a list of Hearth::AuthOptions to consider for every operation call. The Auth Option can also include custom identity and signing properties if necessary.

class ApiKeyAuthResolver
  def resolve(params)
    # custom logic - perhaps always use API Key auth for every operation
    [Hearth::AuthOption.new(scheme_id: 'smithy.api#httpApiKeyAuth')]
  end
end
# => :resolve

HighScoreService::Client.new(
  endpoint: 'http://127.0.0.1:3000',
  auth_resolver: ApiKeyAuthResolver.new
)
# => #<HighScoreService::Client ... >

client.list_high_scores
# <Signs with API key>
# => #<Hearth::Output @data=... >

The Auth Scheme list is a mechanism to enable or disable Auth Schemes for the Client across all operations. Additionally, custom Signers can be configured onto an Auth Scheme and passed to this list. If the operation is modeled to use another auth scheme first, that auth scheme is not considered. For example, if the Auth Resolver returns a priority list of HTTP Basic auth and HTTP API Key auth, only HTTP API Key auth will be considered.

auth_schemes = [Hearth::AuthSchemes::HTTPApiKey.new]
# => [#<Hearth::AuthSchemes::HTTPApiKey ... >]

HighScoreService::Client.new(
  endpoint: 'http://127.0.0.1:3000',
  auth_schemes: auth_schemes
)
# => #<HighScoreService::Client ... >

client.list_high_scores
# <Signs with API key>
# => #<Hearth::Output @data=... >

Signers

Signers are responsible for signing requests. Sometimes, Signers will need to unsign a request in the event of a retry. Signers must implement the following methods:

• sign(request:, identity:, properties:)
• reset(request:, properties:)