Class: Aws::SSOOIDC::Client

Inherits:

Seahorse::Client::Base

• Object
• Seahorse::Client::Base
• Aws::SSOOIDC::Client

Defined in:

(unknown)

Overview

An API client for AWS SSO OIDC. To construct a client, you need to configure a :region and :credentials.

ssooidc = Aws::SSOOIDC::Client.new(
  region: region_name,
  credentials: credentials,
  # ...
)

See #initialize for a full list of supported configuration options.

Region

You can configure a default region in the following locations:

• ENV['AWS_REGION']
• Aws.config[:region]

Go here for a list of supported regions.

Credentials

Default credentials are loaded automatically from the following locations:

• ENV['AWS_ACCESS_KEY_ID'] and ENV['AWS_SECRET_ACCESS_KEY']
• Aws.config[:credentials]
• The shared credentials ini file at ~/.aws/credentials (more information)
• From an instance profile when running on EC2

You can also construct a credentials object from one of the following classes:

• Credentials
• Aws::SharedCredentials
• InstanceProfileCredentials
• AssumeRoleCredentials

Alternatively, you configure credentials with :access_key_id and :secret_access_key:

# load credentials from disk
creds = YAML.load(File.read('/path/to/secrets'))

Aws::SSOOIDC::Client.new(
  access_key_id: creds['access_key_id'],
  secret_access_key: creds['secret_access_key']
)

Always load your credentials from outside your application. Avoid configuring credentials statically and never commit them to source control.

Attribute Summary

Instance Attribute Summary

Attributes inherited from Seahorse::Client::Base

#config, #handlers

Constructor

• #initialize(options = {}) ⇒ Aws::SSOOIDC::Client constructor

  Constructs an API client.

API Operations

• #create_token(options = {}) ⇒ Types::CreateTokenResponse

  Creates and returns an access token for the authorized client.

• #register_client(options = {}) ⇒ Types::RegisterClientResponse

  Registers a client with AWS SSO.

• #start_device_authorization(options = {}) ⇒ Types::StartDeviceAuthorizationResponse

  Initiates device authorization by requesting a pair of verification codes from the authorization service.

  .

Instance Method Summary

• #wait_until(waiter_name, params = {}) {|waiter| ... } ⇒ Boolean

  Waiters polls an API operation until a resource enters a desired state.

• #waiter_names ⇒ Array<Symbol>

  Returns the list of supported waiters.

Methods inherited from Seahorse::Client::Base

add_plugin, api, #build_request, clear_plugins, define, new, #operation, #operation_names, plugins, remove_plugin, set_api, set_plugins

Methods included from Seahorse::Client::HandlerBuilder

#handle, #handle_request, #handle_response

Constructor Details

#initialize(options = {}) ⇒ Aws::SSOOIDC::Client

Constructs an API client.

Options Hash (options):

• :access_key_id (String) —

  Used to set credentials statically. See Plugins::RequestSigner for more details.

• :active_endpoint_cache (Boolean) —

  When set to true, a thread polling for endpoints will be running in the background every 60 secs (default). Defaults to false. See Plugins::EndpointDiscovery for more details.

• :convert_params (Boolean) — default: true —

  When true, an attempt is made to coerce request parameters into the required types. See Plugins::ParamConverter for more details.

• :credentials (required, Credentials) —

  Your AWS credentials. The following locations will be searched in order for credentials:

  • :access_key_id, :secret_access_key, and :session_token options
  • ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY']
  • HOME/.aws/credentials shared credentials file
  • EC2 instance profile credentials See Plugins::RequestSigner for more details.
• :disable_host_prefix_injection (Boolean) —

  Set to true to disable SDK automatically adding host prefix to default service endpoint when available. See Plugins::EndpointPattern for more details.

• :endpoint (String) —

  A default endpoint is constructed from the :region. See Plugins::RegionalEndpoint for more details.

• :endpoint_cache_max_entries (Integer) —

  Used for the maximum size limit of the LRU cache storing endpoints data for endpoint discovery enabled operations. Defaults to 1000. See Plugins::EndpointDiscovery for more details.

• :endpoint_cache_max_threads (Integer) —

  Used for the maximum threads in use for polling endpoints to be cached, defaults to 10. See Plugins::EndpointDiscovery for more details.

• :endpoint_cache_poll_interval (Integer) —

  When :endpoint_discovery and :active_endpoint_cache is enabled, Use this option to config the time interval in seconds for making requests fetching endpoints information. Defaults to 60 sec. See Plugins::EndpointDiscovery for more details.

• :endpoint_discovery (Boolean) —

  When set to true, endpoint discovery will be enabled for operations when available. Defaults to false. See Plugins::EndpointDiscovery for more details.

• :http_continue_timeout (Float) — default: 1 —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :http_idle_timeout (Integer) — default: 5 —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :http_open_timeout (Integer) — default: 15 —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :http_proxy (String) —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :http_read_timeout (Integer) — default: 60 —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :http_wire_trace (Boolean) — default: false —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :log_level (Symbol) — default: :info —

  The log level to send messages to the logger at. See Plugins::Logging for more details.

• :log_formatter (Logging::LogFormatter) —

  The log formatter. Defaults to Seahorse::Client::Logging::Formatter.default. See Plugins::Logging for more details.

• :logger (Logger) — default: nil —

  The Logger instance to send log messages to. If this option is not set, logging will be disabled. See Plugins::Logging for more details.

• :profile (String) —

  Used when loading credentials from the shared credentials file at HOME/.aws/credentials. When not specified, 'default' is used. See Plugins::RequestSigner for more details.

• :raise_response_errors (Boolean) — default: true —

  When true, response errors are raised. See Seahorse::Client::Plugins::RaiseResponseErrors for more details.

• :region (required, String) —

  The AWS region to connect to. The region is used to construct the client endpoint. Defaults to ENV['AWS_REGION']. Also checks AMAZON_REGION and AWS_DEFAULT_REGION. See Plugins::RegionalEndpoint for more details.

• :retry_limit (Integer) — default: 3 —

  The maximum number of times to retry failed requests. Only ~ 500 level server errors and certain ~ 400 level client errors are retried. Generally, these are throttling errors, data checksum errors, networking errors, timeout errors and auth errors from expired credentials. See Plugins::RetryErrors for more details.

• :secret_access_key (String) —

  Used to set credentials statically. See Plugins::RequestSigner for more details.

• :session_token (String) —

  Used to set credentials statically. See Plugins::RequestSigner for more details.

• :ssl_ca_bundle (String) —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :ssl_ca_directory (String) —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :ssl_ca_store (String) —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :ssl_verify_peer (Boolean) — default: true —

  See Seahorse::Client::Plugins::NetHttp for more details.

• :stub_responses (Boolean) — default: false —

  Causes the client to return stubbed responses. By default fake responses are generated and returned. You can specify the response data to return or errors to raise by calling ClientStubs#stub_responses. See ClientStubs for more information.

  Please note When response stubbing is enabled, no HTTP requests are made, and retries are disabled. See Plugins::StubResponses for more details.

• :validate_params (Boolean) — default: true —

  When true, request parameters are validated before sending the request. See Plugins::ParamValidator for more details.

Instance Method Details

#create_token(options = {}) ⇒ Types::CreateTokenResponse

Creates and returns an access token for the authorized client. The access token issued will be used to fetch short-term credentials for the assigned roles in the AWS account.

Examples:

Request syntax with placeholder values

resp = client.create_token({
  client_id: "ClientId", # required
  client_secret: "ClientSecret", # required
  grant_type: "GrantType", # required
  device_code: "DeviceCode", # required
  code: "AuthCode",
  refresh_token: "RefreshToken",
  scope: ["Scope"],
  redirect_uri: "URI",
})

Response structure

resp.access_token #=> String
resp.token_type #=> String
resp.expires_in #=> Integer
resp.refresh_token #=> String
resp.id_token #=> String

Options Hash (options):

• :client_id (required, String) —

  The unique identifier string for each client. This value should come from the persisted result of the RegisterClient API.

• :client_secret (required, String) —

  A secret string generated for the client. This value should come from the persisted result of the RegisterClient API.

• :grant_type (required, String) —

  Supports grant types for authorization code, refresh token, and device code request.

• :device_code (required, String) —

  Used only when calling this API for the device code grant type. This short-term code is used to identify this authentication attempt. This should come from an in-memory reference to the result of the StartDeviceAuthorization API.

• :code (String) —

  The authorization code received from the authorization service. This parameter is required to perform an authorization grant request to get access to a token.

• :refresh_token (String) —

  The token used to obtain an access token in the event that the access token is invalid or expired. This token is not issued by the service.

• :scope (Array<String>) —

  The list of scopes that is defined by the client. Upon authorization, this list is used to restrict permissions when granting an access token.

• :redirect_uri (String) —

  The location of the application that will receive the authorization code. Users authorize the service to send the request to this location.

Returns:

• (Types::CreateTokenResponse) —

  Returns a response object which responds to the following methods:

  • #access_token => String
  • #token_type => String
  • #expires_in => Integer
  • #refresh_token => String
  • #id_token => String

See Also:

• AWS API Documentation

#register_client(options = {}) ⇒ Types::RegisterClientResponse

Registers a client with AWS SSO. This allows clients to initiate device authorization. The output should be persisted for reuse through many authentication requests.

Examples:

Request syntax with placeholder values

resp = client.register_client({
  client_name: "ClientName", # required
  client_type: "ClientType", # required
  scopes: ["Scope"],
})

Response structure

resp.client_id #=> String
resp.client_secret #=> String
resp.client_id_issued_at #=> Integer
resp.client_secret_expires_at #=> Integer
resp.authorization_endpoint #=> String
resp.token_endpoint #=> String

Options Hash (options):

• :client_name (required, String) —

  The friendly name of the client.

• :client_type (required, String) —

  The type of client. The service supports only public as a client type. Anything other than public will be rejected by the service.

• :scopes (Array<String>) —

  The list of scopes that are defined by the client. Upon authorization, this list is used to restrict permissions when granting an access token.

Returns:

• (Types::RegisterClientResponse) —

  Returns a response object which responds to the following methods:

  • #client_id => String
  • #client_secret => String
  • #client_id_issued_at => Integer
  • #client_secret_expires_at => Integer
  • #authorization_endpoint => String
  • #token_endpoint => String

See Also:

• AWS API Documentation

#start_device_authorization(options = {}) ⇒ Types::StartDeviceAuthorizationResponse

Initiates device authorization by requesting a pair of verification codes from the authorization service.

Examples:

Request syntax with placeholder values

resp = client.start_device_authorization({
  client_id: "ClientId", # required
  client_secret: "ClientSecret", # required
  start_url: "URI", # required
})

Response structure

resp.device_code #=> String
resp.user_code #=> String
resp.verification_uri #=> String
resp.verification_uri_complete #=> String
resp.expires_in #=> Integer
resp.interval #=> Integer

Options Hash (options):

• :client_id (required, String) —

  The unique identifier string for the client that is registered with AWS SSO. This value should come from the persisted result of the RegisterClient API operation.

• :client_secret (required, String) —

  A secret string that is generated for the client. This value should come from the persisted result of the RegisterClient API operation.

• :start_url (required, String) —

  The URL for the AWS SSO user portal. For more information, see Using the User Portal in the AWS Single Sign-On User Guide.

Returns:

• (Types::StartDeviceAuthorizationResponse) —

  Returns a response object which responds to the following methods:

  • #device_code => String
  • #user_code => String
  • #verification_uri => String
  • #verification_uri_complete => String
  • #expires_in => Integer
  • #interval => Integer

See Also:

• AWS API Documentation

#wait_until(waiter_name, params = {}) {|waiter| ... } ⇒ Boolean

Waiters polls an API operation until a resource enters a desired state.

Basic Usage

Waiters will poll until they are succesful, they fail by entering a terminal state, or until a maximum number of attempts are made.

# polls in a loop, sleeping between attempts client.waiter_until(waiter_name, params)

Configuration

You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. You configure waiters by passing a block to #wait_until:

# poll for ~25 seconds
client.wait_until(...) do |w|
  w.max_attempts = 5
  w.delay = 5
end

Callbacks

You can be notified before each polling attempt and before each delay. If you throw :success or :failure from these callbacks, it will terminate the waiter.

started_at = Time.now
client.wait_until(...) do |w|

  # disable max attempts
  w.max_attempts = nil

  # poll for 1 hour, instead of a number of attempts
  w.before_wait do |attempts, response|
    throw :failure if Time.now - started_at > 3600
  end

end

Handling Errors

When a waiter is successful, it returns true. When a waiter fails, it raises an error. All errors raised extend from Waiters::Errors::WaiterFailed.

begin
  client.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
  # resource did not enter the desired state in time
end

Parameters:

• waiter_name (Symbol) —

  The name of the waiter. See #waiter_names for a full list of supported waiters.

• params (Hash) (defaults to: {}) —

  Additional request parameters. See the #waiter_names for a list of supported waiters and what request they call. The called request determines the list of accepted parameters.

Yield Parameters:

• waiter (Waiters::Waiter) —

  Yields a Waiter object that can be configured prior to waiting.

Returns:

• (Boolean) —

  Returns true if the waiter was successful.

Raises:

• (Errors::FailureStateError) —

  Raised when the waiter terminates because the waiter has entered a state that it will not transition out of, preventing success.

• (Errors::TooManyAttemptsError) —

  Raised when the configured maximum number of attempts have been made, and the waiter is not yet successful.

• (Errors::UnexpectedError) —

  Raised when an error is encounted while polling for a resource that is not expected.

• (Errors::NoSuchWaiterError) —

  Raised when you request to wait for an unknown state.

#waiter_names ⇒ Array<Symbol>

Returns the list of supported waiters. The following table lists the supported waiters and the client method they call:

Waiter Name	Client Method	Default Delay:	Default Max Attempts:

Returns:

• (Array<Symbol>) —

  the list of supported waiters.