Class: Aws::CognitoIdentity::CognitoIdentityCredentials

Inherits:
Object
  • Object
show all
Includes:
Aws::CredentialProvider, RefreshingCredentials
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.

Constant Summary

Constants included from RefreshingCredentials

RefreshingCredentials::ASYNC_EXPIRATION_LENGTH, RefreshingCredentials::CLIENT_EXCLUDE_OPTIONS, RefreshingCredentials::SYNC_EXPIRATION_LENGTH

Instance Attribute Summary collapse

Attributes included from Aws::CredentialProvider

#credentials, #expiration

Instance Method Summary collapse

Methods included from RefreshingCredentials

#credentials, #refresh!

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