AWS Single Sign-On

(1)

AWS Single Sign-On

API Reference

(2)

AWS Single Sign-On: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome to the AWS Single Sign-On API Reference Guide

AWS Single Sign-On (SSO) is a cloud SSO service that makes it easy to centrally manage SSO access to multiple AWS accounts and business applications. This guide provides information on SSO operations which could be used for access management of AWS accounts. For information about AWS SSO features, see the AWS Single Sign-On User Guide.

Many operations in the AWS SSO APIs rely on identiﬁers for users and groups, known as principals. For more information about how to work with principals and principal IDs in AWS SSO, see the AWS SSO Identity Store API Reference.

NoteAWS provides SDKs that consist of libraries and sample code for various programming languages and platforms (Java, Ruby, .Net, iOS, Android, and more). The SDKs provide a convenient way to create programmatic access to AWS SSO and other AWS services. For more information about the AWS SDKs, including how to download and install them, see Tools for Amazon Web Services.

(9)

Actions

The following actions are supported:

• AttachManagedPolicyToPermissionSet (p. 3)

• CreateAccountAssignment (p. 6)

• CreateInstanceAccessControlAttributeConﬁguration (p. 10)

• CreatePermissionSet (p. 12)

• DeleteAccountAssignment (p. 16)

• DeleteInlinePolicyFromPermissionSet (p. 20)

• DeleteInstanceAccessControlAttributeConﬁguration (p. 22)

• DeletePermissionSet (p. 24)

• DescribeAccountAssignmentCreationStatus (p. 26)

• DescribeAccountAssignmentDeletionStatus (p. 29)

• DescribeInstanceAccessControlAttributeConﬁguration (p. 32)

• DescribePermissionSet (p. 35)

• DescribePermissionSetProvisioningStatus (p. 38)

• DetachManagedPolicyFromPermissionSet (p. 41)

• GetInlinePolicyForPermissionSet (p. 44)

• ListAccountAssignmentCreationStatus (p. 47)

• ListAccountAssignmentDeletionStatus (p. 50)

• ListAccountAssignments (p. 53)

• ListAccountsForProvisionedPermissionSet (p. 56)

• ListInstances (p. 59)

• ListManagedPoliciesInPermissionSet (p. 62)

• ListPermissionSetProvisioningStatus (p. 65)

• ListPermissionSets (p. 68)

• ListPermissionSetsProvisionedToAccount (p. 71)

• ListTagsForResource (p. 74)

• ProvisionPermissionSet (p. 77)

• PutInlinePolicyToPermissionSet (p. 80)

• TagResource (p. 83)

• UntagResource (p. 86)

• UpdateInstanceAccessControlAttributeConﬁguration (p. 89)

• UpdatePermissionSet (p. 91)

(10)

AttachManagedPolicyToPermissionSet

Attaches an IAM managed policy ARN to a permission set.

NoteIf the permission set is already referenced by one or more account assignments, you will need to call ProvisionPermissionSet (p. 77) after this operation. Calling ProvisionPermissionSet applies the corresponding IAM policy updates to all assigned accounts.

Request Syntax

{ "InstanceArn": "string", "ManagedPolicyArn": "string", "PermissionSetArn": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 112).

The request accepts the following data in JSON format.

InstanceArn (p. 3)

The ARN of the SSO instance under which the operation will be executed. For more information about ARNs, see Amazon Resource Names (ARNs) and AWS Service Namespaces in the AWS General Reference.

Type: String

Length Constraints: Minimum length of 10. Maximum length of 1224.

Pattern: arn:(aws|aws-us-gov|aws-cn|aws-iso|aws-iso-b):sso:::instance/(sso)?

ins-[a-zA-Z0-9-.]{16}

Required: Yes ManagedPolicyArn (p. 3)

The IAM managed policy ARN to be attached to a permission set.

Type: String

Required: Yes PermissionSetArn (p. 3)

The ARN of the PermissionSet (p. 106) that the managed policy should be attached to.

Type: String

Pattern: arn:(aws|aws-us-gov|aws-cn|aws-iso|aws-iso-b):sso:::permissionSet/

(sso)?ins-[a-zA-Z0-9-.]{16}/ps-[a-zA-Z0-9-./]{16}

(11)

Response Elements

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors (p. 114).

AccessDeniedException

You do not have suﬃcient access to perform this action.

HTTP Status Code: 400 ConﬂictException

Occurs when a conﬂict with a previous successful write is detected. This generally occurs when the previous write did not have time to propagate to the host serving the current request. A retry (with appropriate backoﬀ logic) is the recommended response to this exception.

HTTP Status Code: 400 InternalServerException

The request processing has failed because of an unknown error, exception, or failure with an internal server.

HTTP Status Code: 400 ResourceNotFoundException

Indicates that a requested resource is not found.

HTTP Status Code: 400 ServiceQuotaExceededException

Indicates that the principal has crossed the permitted number of resources that can be created.

HTTP Status Code: 400 ThrottlingException

Indicates that the principal has crossed the throttling limits of the API operations.

HTTP Status Code: 400 ValidationException

The request failed because it contains a syntax error.

HTTP Status Code: 400

CreateAccountAssignment

Assigns access to a principal for a speciﬁed AWS account using a speciﬁed permission set.

NoteThe term principal here refers to a user or group that is deﬁned in AWS SSO.

NoteAs part of a successful CreateAccountAssignment call, the speciﬁed permission set will automatically be provisioned to the account in the form of an IAM policy. That policy is attached to the SSO-created IAM role. If the permission set is subsequently updated, the corresponding IAM policies attached to roles in your accounts will not be updated automatically. In this case, you must call ProvisionPermissionSet (p. 77) to make these updates.

Request Syntax

{

"InstanceArn": "string", "PermissionSetArn": "string", "PrincipalId": "string", "PrincipalType": "string", "TargetId": "string", "TargetType": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

The ARN of the permission set that the admin wants to grant the principal access to.

Type: String

Required: Yes

(14)

Response Syntax

PrincipalId (p. 6)

An identiﬁer for an object in AWS SSO, such as a user or group. PrincipalIds are GUIDs (For example, f81d4fae-7dec-11d0-a765-00a0c91e6bf6). For more information about PrincipalIds in AWS SSO, see the AWS SSO Identity Store API Reference.

Type: String

Pattern: ^([0-9a-f]{10}-|)[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa- f0-9]{4}-[A-Fa-f0-9]{12}$

Required: Yes PrincipalType (p. 6)

The entity type for which the assignment will be created.

Type: String

Valid Values: USER | GROUP Required: Yes

TargetId (p. 6)

TargetID is an AWS account identiﬁer, typically a 10-12 digit string (For example, 123456789012).

Type: String

Length Constraints: Fixed length of 12.

Pattern: \d{12}

Required: Yes TargetType (p. 6)

The entity type for which the assignment will be created.

Type: String

Valid Values: AWS_ACCOUNT Required: Yes

Response Syntax

{ "AccountAssignmentCreationStatus": { "CreatedDate": number,

"FailureReason": "string", "PermissionSetArn": "string", "PrincipalId": "string", "PrincipalType": "string", "RequestId": "string", "Status": "string", "TargetId": "string", "TargetType": "string"

}

(15)

Response Elements

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

AccountAssignmentCreationStatus (p. 7)

The status object for the account assignment creation operation.

Type: AccountAssignmentOperationStatus (p. 99) object

Errors

(16)

See Also

CreateInstanceAccessControlAttributeConﬁguration

Enables the attributes-based access control (ABAC) feature for the speciﬁed AWS SSO instance. You can also specify new attributes to add to your ABAC conﬁguration during the enabling process. For more information about ABAC, see Attribute-Based Access Control in the AWS SSO User Guide.

Request Syntax

{

"InstanceAccessControlAttributeConfiguration": { "AccessControlAttributes": [

{

"Key": "string", "Value": {

"Source": [ "string" ] }

} ] },

"InstanceArn": "string"

}

Request Parameters

InstanceAccessControlAttributeConﬁguration (p. 10)

Speciﬁes the AWS SSO identity store attributes to add to your ABAC conﬁguration. When using an external identity provider as an identity source, you can pass attributes through the SAML assertion.

Doing so provides an alternative to conﬁguring attributes from the AWS SSO identity store. If a SAML assertion passes any of these attributes, AWS SSO will replace the attribute value with the value from the AWS SSO identity store.

Type: InstanceAccessControlAttributeConﬁguration (p. 103) object Required: Yes

The ARN of the SSO instance under which the operation will be executed.

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes

Response Elements

(18)

Errors

CreatePermissionSet

Creates a permission set within a speciﬁed SSO instance.

NoteTo grant users and groups access to AWS account resources, use CreateAccountAssignment (p. 6) .

Request Syntax

{ "Description": "string", "InstanceArn": "string", "Name": "string",

"RelayState": "string", "SessionDuration": "string", "Tags": [

{

"Key": "string", "Value": "string"

} ] }

Request Parameters

Description (p. 12)

The description of the PermissionSet (p. 106).

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u00A0-\u00FF]*

Required: No InstanceArn (p. 12)

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes Name (p. 12)

The name of the PermissionSet (p. 106).

(20)

Response Syntax

Type: String

Pattern: [\w+=,.@-]+

Required: Yes RelayState (p. 12)

Used to redirect users within the application during the federation authentication process.

Type: String

Pattern: [a-zA-Z0-9&$@#\\\/%?=~\-_'"|!:,.;*+\[\]\ \{\}]+

Required: No SessionDuration (p. 12)

The length of time that the application user sessions are valid in the ISO-8601 standard.

Type: String

Pattern: ^(-?)P(?=\d|T\d)(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)([DW]))?(?:T(?:(\d+)H)?

(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$

Required: No Tags (p. 12)

The tags to attach to the new PermissionSet (p. 106).

Type: Array of Tag (p. 111) objects

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: No

Response Syntax

{

"PermissionSet": { "CreatedDate": number, "Description": "string", "Name": "string",

"PermissionSetArn": "string", "RelayState": "string", "SessionDuration": "string"

}}

Response Elements

(21)

Errors

PermissionSet (p. 13)

Deﬁnes the level of access on an AWS account.

Type: PermissionSet (p. 106) object

Errors

DeleteAccountAssignment

Deletes a principal's access from a speciﬁed AWS account using a speciﬁed permission set.

Request Syntax

{

"InstanceArn": "string", "PermissionSetArn": "string", "PrincipalId": "string", "PrincipalType": "string", "TargetId": "string", "TargetType": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

The ARN of the permission set that will be used to remove access.

Type: String

Required: Yes PrincipalId (p. 16)

An identiﬁer for an object in AWS SSO, such as a user or group. PrincipalIds are GUIDs (For example, f81d4fae-7dec-11d0-a765-00a0c91e6bf6). For more information about PrincipalIds in AWS SSO, see the AWS SSO Identity Store API Reference.

Type: String

(24)

Response Syntax

Pattern: ^([0-9a-f]{10}-|)[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa- f0-9]{4}-[A-Fa-f0-9]{12}$

Required: Yes PrincipalType (p. 16)

The entity type for which the assignment will be deleted.

Type: String

Valid Values: USER | GROUP Required: Yes

TargetId (p. 16)

TargetID is an AWS account identiﬁer, typically a 10-12 digit string (For example, 123456789012).

Type: String

Pattern: \d{12}

Required: Yes TargetType (p. 16)

The entity type for which the assignment will be deleted.

Type: String

Valid Values: AWS_ACCOUNT Required: Yes

Response Syntax

{

"AccountAssignmentDeletionStatus": { "CreatedDate": number,

"FailureReason": "string", "PermissionSetArn": "string", "PrincipalId": "string", "PrincipalType": "string", "RequestId": "string", "Status": "string", "TargetId": "string", "TargetType": "string"

}}

Response Elements

AccountAssignmentDeletionStatus (p. 17)

The status object for the account assignment deletion operation.

(25)

Errors

DeleteInlinePolicyFromPermissionSet

Deletes the inline policy from a speciﬁed permission set.

Request Syntax

{ "InstanceArn": "string", "PermissionSetArn": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

The ARN of the permission set that will be used to remove access.

Type: String

Required: Yes

Response Elements

Errors

(28)

See Also

DeleteInstanceAccessControlAttributeConﬁguration

Disables the attributes-based access control (ABAC) feature for the specified AWS SSO instance and deletes all of the attribute mappings that have been configured. Once deleted, any attributes that are received from an identity source and any custom attributes you have previously configured will not be passed. For more information about ABAC, see Attribute-Based Access Control in the AWS SSO User Guide.

Request Syntax

{ "InstanceArn": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes

Response Elements

Errors

(30)

See Also

InternalServerException

DeletePermissionSet

Deletes the speciﬁed permission set.

Request Syntax

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

The ARN of the permission set that should be deleted.

Type: String

Required: Yes

Response Elements

Errors

(32)

See Also

DescribeAccountAssignmentCreationStatus

Describes the status of the assignment creation request.

Request Syntax

{ "AccountAssignmentCreationRequestId": "string", "InstanceArn": "string"

}

Request Parameters

AccountAssignmentCreationRequestId (p. 26)

The identiﬁer that is used to track the request operation progress.

Type: String

Pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b Required: Yes

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes

Response Syntax

{ "AccountAssignmentCreationStatus": { "CreatedDate": number,

"FailureReason": "string", "PermissionSetArn": "string", "PrincipalId": "string", "PrincipalType": "string", "RequestId": "string", "Status": "string",

(34)

Response Elements

"TargetId": "string", "TargetType": "string"

}}

Response Elements

AccountAssignmentCreationStatus (p. 26)

Errors

DescribeAccountAssignmentDeletionStatus

Describes the status of the assignment deletion request.

Request Syntax

{ "AccountAssignmentDeletionRequestId": "string", "InstanceArn": "string"

}

Request Parameters

AccountAssignmentDeletionRequestId (p. 29)

The identiﬁer that is used to track the request operation progress.

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes

Response Syntax

{ "AccountAssignmentDeletionStatus": { "CreatedDate": number,

"FailureReason": "string", "PermissionSetArn": "string", "PrincipalId": "string", "PrincipalType": "string", "RequestId": "string", "Status": "string",

(37)

Response Elements

"TargetId": "string", "TargetType": "string"

}}

Response Elements

AccountAssignmentDeletionStatus (p. 29)

The status object for the account assignment deletion operation.

Errors

DescribeInstanceAccessControlAttributeConﬁguration

Returns the list of AWS SSO identity store attributes that have been conﬁgured to work with attributes- based access control (ABAC) for the speciﬁed AWS SSO instance. This will not return attributes

conﬁgured and sent by an external identity provider. For more information about ABAC, see Attribute- Based Access Control in the AWS SSO User Guide.

Request Syntax

{ "InstanceArn": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes

Response Syntax

{

"InstanceAccessControlAttributeConfiguration": { "AccessControlAttributes": [

{

"Key": "string", "Value": {

"Source": [ "string" ] }

} ] },

"Status": "string", "StatusReason": "string"

}

Response Elements

(40)

Errors

InstanceAccessControlAttributeConﬁguration (p. 32)

Gets the list of AWS SSO identity store attributes that have been added to your ABAC conﬁguration.

Type: InstanceAccessControlAttributeConﬁguration (p. 103) object Status (p. 32)

The status of the attribute conﬁguration process.

Type: String

Valid Values: ENABLED | CREATION_IN_PROGRESS | CREATION_FAILED StatusReason (p. 32)

Provides more details about the current status of the speciﬁed attribute.

Type: String

Errors

DescribePermissionSet

Gets the details of the permission set.

Request Syntax

{

"InstanceArn": "string", "PermissionSetArn": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

The ARN of the permission set.

Type: String

Required: Yes

Response Syntax

{

"PermissionSet": { "CreatedDate": number, "Description": "string", "Name": "string",

"PermissionSetArn": "string", "RelayState": "string", "SessionDuration": "string"

(43)

Response Elements

} }

Response Elements

PermissionSet (p. 35)

Describes the level of access on an AWS account.

Type: PermissionSet (p. 106) object

Errors

DescribePermissionSetProvisioningStatus

Describes the status for the given permission set provisioning request.

Request Syntax

{

"InstanceArn": "string",

"ProvisionPermissionSetRequestId": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes

ProvisionPermissionSetRequestId (p. 38)

The identiﬁer that is provided by the ProvisionPermissionSet (p. 77) call to retrieve the current status of the provisioning workﬂow.

Type: String

Response Syntax

{

"PermissionSetProvisioningStatus": { "AccountId": "string",

"CreatedDate": number, "FailureReason": "string", "PermissionSetArn": "string", "RequestId": "string", "Status": "string"

(46)

Response Elements

} }

Response Elements

PermissionSetProvisioningStatus (p. 38)

The status object for the permission set provisioning operation.

Type: PermissionSetProvisioningStatus (p. 108) object

Errors

DetachManagedPolicyFromPermissionSet

Detaches the attached IAM managed policy ARN from the speciﬁed permission set.

Request Syntax

{

"InstanceArn": "string", "ManagedPolicyArn": "string", "PermissionSetArn": "string"

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes

ManagedPolicyArn (p. 41)

The IAM managed policy ARN to be detached from a permission set.

Type: String

The ARN of the PermissionSet (p. 106) from which the policy should be detached.

Type: String

Required: Yes

(49)

Response Elements

Errors

GetInlinePolicyForPermissionSet

Obtains the inline policy assigned to the permission set.

Request Syntax

}

Request Parameters

Type: String

ins-[a-zA-Z0-9-.]{16}

The ARN of the permission set.

Type: String

Required: Yes

Response Syntax

{ "InlinePolicy": "string"

}

Response Elements

(52)

Errors

InlinePolicy (p. 44)

The IAM inline policy that is attached to the permission set.

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u00FF]+

Errors

ListAccountAssignmentCreationStatus

Lists the status of the AWS account assignment creation requests for a speciﬁed SSO instance.

Request Syntax

{ "Filter": {

"Status": "string"

},

"InstanceArn": "string", "MaxResults": number, "NextToken": "string"

}

Request Parameters

Filter (p. 47)

Filters results based on the passed attribute value.

Type: OperationStatusFilter (p. 105) object Required: No

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes MaxResults (p. 47)

The maximum number of results to display for the assignment.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No NextToken (p. 47)

The pagination token for the list API. Initially the value is null. Use the output of previous API calls to make subsequent calls.

(55)

Response Syntax

Type: String

Length Constraints: Maximum length of 2048.

Pattern: ^[-a-zA-Z0-9+=/_]*

Required: No

Response Syntax

{ "AccountAssignmentsCreationStatus": [ {

"CreatedDate": number, "RequestId": "string", "Status": "string"

} ],

"NextToken": "string"

}

Response Elements

AccountAssignmentsCreationStatus (p. 48)

Type: Array of AccountAssignmentOperationStatusMetadata (p. 101) objects NextToken (p. 48)

Type: String

Length Constraints: Maximum length of 2048.

Pattern: ^[-a-zA-Z0-9+=/_]*

Errors

(56)

See Also

ListAccountAssignmentDeletionStatus

Lists the status of the AWS account assignment deletion requests for a speciﬁed SSO instance.

Request Syntax

{ "Filter": {

"Status": "string"

},

"InstanceArn": "string", "MaxResults": number, "NextToken": "string"

}

Request Parameters

Filter (p. 50)

Filters results based on the passed attribute value.

Type: OperationStatusFilter (p. 105) object Required: No

Type: String

ins-[a-zA-Z0-9-.]{16}

Required: Yes MaxResults (p. 50)

The maximum number of results to display for the assignment.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No NextToken (p. 50)

AWS Single Sign-On

AWS Single Sign-On

API Reference

AWS Single Sign-On: API Reference

Table of Contents

Welcome to the AWS Single Sign-On API Reference Guide

Actions

AttachManagedPolicyToPermissionSet

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CreateAccountAssignment

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateInstanceAccessControlAttributeConﬁguration

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CreatePermissionSet

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DeleteAccountAssignment

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DeleteInlinePolicyFromPermissionSet

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeleteInstanceAccessControlAttributeConﬁguration

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeletePermissionSet

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DescribeAccountAssignmentCreationStatus

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DescribeAccountAssignmentDeletionStatus

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DescribeInstanceAccessControlAttributeConﬁguration

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

DescribePermissionSet