Class: Aws::CognitoIdentity::CognitoIdentityCredentials

Inherits:
Object
  • Object
show all
Includes:
Aws::CredentialProvider
Defined in:
gems/aws-sdk-cognitoidentity/lib/aws-sdk-cognitoidentity/customizations/cognito_identity_credentials.rb

Overview

An auto-refreshing credential provider that represents credentials retrieved from STS Web Identity Federation using the Amazon Cognito Identity service.

This provider gets credentials using the Aws::CognitoIdentity::Client#get_credentials_for_identity service operation, which requires either an identity_id or an identity_pool_id (Amazon Cognito Identity Pool ID), which is used to call Aws::CognitoIdentity::Client#get_id to obtain an identity_id automatically.

In addition, if this credential provider is used to provide authenticated login, the logins map may be set to the tokens provided by the respective identity providers. See #initialize for an example on creating a credentials object with proper property values.

Refreshing Credentials from Identity Service

The CognitoIdentityCredentials will auto-refresh the AWS credentials from Cognito. In addition to AWS credentials expiring after a given amount of time, the login token from the identity provider will also expire. Once this token expires, it will not be usable to refresh AWS credentials, and another token will be needed. The SDK does not manage refreshing of the token value, but this can be done through a "refresh token" supported by most identity providers. Consult the documentation for the identity provider for refreshing tokens. Once the refreshed token is acquired, you should make sure to update this new token in the CognitoIdentityCredentials object's #logins property. The following code will update the WebIdentityToken, assuming you have retrieved an updated token from the identity provider:

cognito_credentials.logins['graph.facebook.com'] = updatedToken;
cognito_credentials.refresh!  # required only if authentication state has changed

The CognitoIdentityCredentials also provides a before_refresh callback that can be used to help manage refreshing identity provider tokens. before_refresh is called when AWS credentials are required and need to be refreshed and it has access to the CognitoIdentityCredentials object.

Instance Attribute Summary collapse

Attributes included from Aws::CredentialProvider

#credentials, #expiration

Instance Method Summary collapse

Methods included from Aws::CredentialProvider

#set?

Constructor Details

#initialize(options = {}) ⇒ CognitoIdentityCredentials

Returns a new instance of CognitoIdentityCredentials.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :identity_id (String) —

    the Cognito identity_id. Required unless identity_pool_id is given. A unique identifier in the format REGION:GUID

  • :identity_pool_id (String) —

    Required unless identity_id is provided. An Amazon Cognito Identity Pool ID in the format REGION:GUID.

  • :logins (Hash<String,String>) —

    A set of optional name-value pairs that map provider names to provider tokens. The name-value pair will follow the syntax "provider_name": "provider_user_identifier".

  • :custom_role_arn (String) —

    The Amazon Resource Name (ARN) of the role to be assumed when multiple roles were received in the token from the identity provider. For example, a SAML-based identity provider. This parameter is optional for identity providers that do not support role customization.

  • before_refresh (Callable) —

    Proc called before credentials are refreshed from Cognito. before_refresh is called when AWS credentials are required and need to be refreshed. Login tokens can be refreshed using the following example:

    before_refresh = Proc.new do |cognito_credentials| do cognito_credentials.logins['graph.facebook.com'] = update_token end

  • :client (CognitoIdentity::Client) —

    Optional CognitoIdentity client. If not provided, a client will be constructed.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'gems/aws-sdk-cognitoidentity/lib/aws-sdk-cognitoidentity/customizations/cognito_identity_credentials.rb', line 81

def initialize(options = {})
  @identity_pool_id = options.delete(:identity_pool_id)
  @identity_id = options.delete(:identity_id)
  @custom_role_arn = options.delete(:custom_role_arn)
  @logins = options.delete(:logins) || {}
  @async_refresh = false

  client_opts = {}
  options.each_pair { |k, v| client_opts[k] = v unless CLIENT_EXCLUDE_OPTIONS.include?(k) }

  unless @identity_pool_id || @identity_id
    raise ArgumentError,
          'Must provide either identity_pool_id or identity_id'
  end

  @client = options[:client] || CognitoIdentity::Client.new(
    client_opts.merge(credentials: false)
  )
  super
end

Instance Attribute Details

#client ⇒ CognitoIdentity::Client (readonly)

Returns:



103
104
105
 
# File 'gems/aws-sdk-cognitoidentity/lib/aws-sdk-cognitoidentity/customizations/cognito_identity_credentials.rb', line 103

def client
  @client
end

#logins ⇒ Hash<String,String>

Returns:

  • (Hash<String,String>) 


106
107
108
 
# File 'gems/aws-sdk-cognitoidentity/lib/aws-sdk-cognitoidentity/customizations/cognito_identity_credentials.rb', line 106

def logins
  @logins
end

Instance Method Details

#identity_id ⇒ String

Returns:

  • (String) 


109
110
111
112
113
114
 
# File 'gems/aws-sdk-cognitoidentity/lib/aws-sdk-cognitoidentity/customizations/cognito_identity_credentials.rb', line 109

def identity_id
  @identity_id ||= @client.get_id(
    identity_pool_id: @identity_pool_id,
    logins: @logins
  ).identity_id
end