> For the complete documentation index, see [llms.txt](https://permitzip.gitbook.io/dev-bible/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://permitzip.gitbook.io/dev-bible/security/authorization/single-sign-on.md).

# Single Sign-On

Reference material on our approach to Amazon Web Services access and security

The primary benefit of using Single Sign-On (SSO) is easing the complexity involved in humans switching between resources and accounts.

![How SSO Works in AWS](https://2352305786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrcAyGIlakmAAexNxXiMS%2Fuploads%2Fgit-blob-05efa7451876ed8b9697169e6e275b547b2d448c%2Fimage%20\(4\).png?alt=media)

Permissions with Amazon Web Services (AWS) are broken into two major categories of control:

* Single Sign-On (SSO)
* Identity Access Management (IAM)

## Single Sign-On (SSO)

Amazon Web Services (AWS) Single Sign-On (SSO) has a vast security system, but a few concepts are important to fully understand before interacting with the system in any way:

* [**Accounts**](#accounts)
* [**Permission Sets**](#permission-sets)
* [**Groups**](#groups)
* [**Users**](#users)

The primary way to manage access is through an individual user's membership in [**Groups**](#groups) with predefined access.

{% hint style="info" %}
Amazon's [**IAM (Identity and Access Management)**](#iam-identity-access-management) system is a distinct security system from SSO. It is an older system than SSO, but still required for access to certain features and by certain entities, and will be discussed briefly.
{% endhint %}

### :technologist: **Accounts**

While they are tied to a specific email address, <mark style="color:orange;">**Accounts, in general, are not associated with a specific user**</mark>**.** Rather, accounts can be thought of as [environments](/dev-bible/getting-started/environments.md)--such as Sandbox, Staging, and Production--with different levels of restricted access for various SSO groups and users. An account can be assigned a [**group**](#groups) (or an individual [**User**](#users), though this is bad practice) with specific access permissions based on existing permission sets.

{% hint style="warning" %}
**If an Account is created with a user's personal email address, note that this email address will have permanent root access to the account.**

R\_emoving the associated user from the organization's SSO registry **does not prevent** them from logging into AWS's standard account login portal and gaining **access to the account with administrative privileges**.\_
{% endhint %}

It is important to recognize that <mark style="color:orange;">**SSO access cannot be accessed or managed from any Account other than the organization's root management account and up to one account with delegated SSO administration access**</mark> (it is best to name this delegated account something like "Security Administration" and to use it for no other purpose).

Unfortunately, this means that giving a user administrative access to an account such as Staging will not allow them to manage user access within that account. To give a user the ability to manage access for specific accounts, it may be possible to give them partial access to the "Security Administration" account, restricted to the management of specific amazon resources; this requires more research. \[Update - there is now a way to do this through OUs (Organizational Units); check <https://aws.amazon.com/blogs/security/how-to-delegate-management-of-identity-in-aws-single-sign-on/> for more details].

### :key2: Permission Sets

Permission sets define the level of access that Groups and Users have to the AWS Accounts in which the permission set is assigned. Keep in mind that while <mark style="color:orange;">**the permission set can be provisioned across multiple accounts**</mark> and <mark style="color:orange;">**applied to unique groups/user sets in each account,**</mark> <mark style="color:orange;">the</mark> <mark style="color:orange;">**name of the permission set is user-facing**</mark>**.** These facts imply two things:

1. Permission Sets are **not** the best place to manage user-specific changes in user access (this is best done in [**groups**](#groups))
2. The **name** of the permission set should be something that describes the <mark style="color:orange;">**type or level of access, and not specific accounts, users, or groups**</mark>**.** For example, the permission set "AccountAdmin" describes administrative access, can be provisioned across several accounts, and in each account can be given to a different set of Groups or Users.\
   (For permission sets that allow access to specific user-tagged, group-tagged, or otherwise filtered resources, **do** set the permission set's name to refer to the filter, as this in effect describes the level of access permitted).

### :family: Groups

Groups are aggregated sets of Users. Groups as a whole can be granted specific access Permissions in specific Accounts, so <mark style="color:orange;">**adding and removing users from Groups is the best way to manage individual access permissions**</mark>**.** These group names are not user-facing, and are best named in such a way that they describe both the access type and the environment (Account) in which group members are granted access; for example, "Admins-Staging".

<mark style="color:orange;">**To grant group access to an Account**</mark>, sign in to an AWS account with SSO management access, and go to AWS Single Sign-On -> AWS Accounts -> \[An Account] -> Assign users or groups -> Groups.

Upon selecting one or more groups and clicking Next, you will be able to select the <mark style="color:orange;">**permission set(s)**</mark> for these groups. These permission sets are what will appear on each group member's sign-in page as options when logging into the Account. <mark style="color:orange;">**To add or remove Users from a Group**</mark>**,** instead, go to AWS Single Sign-On -> Groups.

#### Multiple Permission Sets

A group can be given multiple permission sets. For example, in the Staging account, members of "Cloud9-Staging" may be given the permission set of "Cloud9Access", while members of "Admins-Staging" may be given both this and the permission set of "AccountAdmin".

This permissions structure allows for administrative functions such as starting and stopping EC2 instances, creating image pipelines, etc. A user can then quickly be given multiple access types by adding them to a high-level group.

That said, for groups that encompass lower-level access in this manner, <mark style="color:orange;">**the group name must typically make clear what lower-level access types are encompassed in its scope in order to effectively manage members**</mark>**.** For this reason, it is typically best to use this multiple-access use case sparingly, and only for particularly high-level groups such as "Admins-\[Account]".

### :person\_bald: Users

Users are the individuals that can be granted membership to Groups, thus allowing predefined access types to predefined accounts and environments. These users are tied to both an email address and to a username/password pair defined in AWS SSO. MFA (Multi-Factor Authentication) can also be enabled and/or required.

### :id: Identity Access Management (IAM)

Compared to SSO, IAM is an alternate (and older) way of managing user and application access to AWS resources. IAM may still be necessary to allow applications (rather than users) access, or for users in certain situations where SSO has not yet been fully integrated. Examples of this in May 2022 include the Cloud9 development platform, where SSO users seem to have trouble participating in collaborative sessions; and the AWS Secrets Manager, which appears to require IAM credentials for access from the CLI.