DEV Community: Eric Villa

IAM Users vs Roles

Eric Villa — Thu, 17 Aug 2023 13:07:28 +0000

In this blog post, we will cover IAM User and IAM Role concepts, focusing on best practices and access patterns.
If you are already familiar with IAM User and Role concepts and just want to know what you should opt for based on your use case, feel free to skip to the last section: "When should I go for IAM Users and when for IAM Roles?".

What is an IAM User?

When you create your first AWS account, you sign in with an identity that has full access to all the services and resources in your account. That identity is called the AWS account root user. As soon as you log into the AWS Console with the AWS account root user, you’ve to find a safer pattern to access it. Why? Because credentials associated with the AWS account root user are not disposable; in case of credentials theft, there is no way to invalidate them. That said, you can implement a safer access pattern by creating an IAM Identity called IAM User.

An AWS Identity and Access Management (IAM) user is an entity that you create in AWS. The IAM user represents the human user or workload who uses the IAM user to interact with AWS. A user in AWS consists of a name and credentials.

A brand-new IAM User has, by default, no permissions. To allow an IAM User to access services and resources in the AWS account in which it was created, you’ve to assign an IAM Policy and one or more credentials to it.

As explained in this article by my fellow colleague Alessandro Gaggia, an IAM Policy is a document that allows you to specify what an IAM Identity (in this case, an IAM User) can do on which resources or services, under what conditions. An IAM Policy is not enough to enable the IAM User permission to access resources or services; credentials must be associated with it.

Based on the way you want to access AWS, you have to use different kinds of credentials.

If you want to enable the IAM User to access the AWS Console, you’ve to assign a console password to the IAM User. The IAM User console password cannot be used to access AWS resources or services from the CLI or SDK.

Access to services or resources from the CLI or SDK is called programmatic access. To grant the IAM User programmatic access, you’ve to set up Access Keys; Access Keys that are created and assigned to an IAM User are long-term credentials. It means they’ve no expiration; you can use them to access your AWS account until they’re disabled or deleted. A common best practice to avoid long-term credentials is to rotate IAM User’s Access Keys periodically by deleting the old ones and replacing them with new ones created from scratch. In addition, IAM User Access Keys can be used to generate temporary credentials through the AWS Security Token Service GetSessionToken API.

Another important common best practice consists in requiring multi-factor authentication for all IAM users in your account. With MFA, users must provide two forms of identification: a console password or Access Keys, and a temporary numeric code that's generated on a hardware device or by an application on a smartphone, like Google Authenticator.

IAM Users are an effective instrument if you want to enable a human or application to access resources and services in a specific account, i.e. the one in which the IAM Users lives. But, there are many use cases that go beyond the possibilities of an IAM User. In particular, an IAM User does not fit a scenario in which we need to grant temporary permissions to trusted entities without sharing long-term credentials. Those trusted entities could be outside the boundary of my account (supposed that I have a single one), outside the boundary of AWS, or outside the boundary of my company.

At this point, you may wonder what kind of technology you can exploit to overcome these limits.

When it comes to granting temporary permissions to trusted entities without sharing long-term credentials, the IAM Identity that comes to the rescue is called IAM Role.

IAM Role

An IAM Role is an Identity that you create in your AWS Account. Like an IAM User, an IAM Role has permissions defined in one or more IAM Access Policies associated with it. But, instead of being associated with one person or application, a Role is designed to be assumed by trusted entities. Assuming an IAM Role means generating temporary credentials associated with that IAM Role. These credentials allow us to perform operations against resources or services based on the permissions defined in the IAM Access Policy associated with the IAM Role.

You can define which trusted entities are allowed to assume the role and acquire temporary security credentials using a Trust Policy for an IAM Role. In addition, the trust policy of a role defines the conditions under which the role can be assumed. The trust policy is written in JSON format and is attached to the role.

Here's an example of what a trust policy for an IAM role might look like:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Replace YOUR_ACCOUNT_ID with your actual AWS account ID. In this trust policy, the Principal is set to the root user of the same AWS account (arn:aws:iam::YOUR_ACCOUNT_ID:root). This means that any entity within the account can assume the role.

Please note that while this example demonstrates granting access to any entity within the account, it's important to follow the principle of least privilege. Granting such broad permissions should be done with caution, as it might lead to unintended access and security risks. It's generally recommended to define more specific trust policies that only allow trusted entities that actually need the permissions provided by the role to assume it. It's important to craft trust policies carefully; trust policies, along with the permissions policies attached to the role, play a crucial role in controlling access to AWS resources in a secure and controlled manner.

Let’s deepen some access scenarios in which I can use IAM Roles to grant temporary permissions to trusted entities.

Federated Access from External Identity Provider (IdP)

In some organizations, user identities are managed outside of AWS using an Identity Provider (IdP). To provide users with access to AWS resources, you can enable federated access. This allows users authenticated by the external IdP to access your AWS environment without needing to create IAM Users. Instead, they're granted temporary access using security tokens based on their IdP authentication. This enhances security and reduces the need for separate user accounts in AWS. There are different kinds of federated access protocol, based on the IdP you’re using.

SAML Federated Access

SAML (Security Assertion Markup Language) is a widely used protocol for SSO. When a user from your organization tries to access AWS resources, they authenticate with your external SAML-compatible IdP (such as Microsoft Active Directory Federation Services or Okta). After successful authentication, the IdP generates a SAML assertion, which is a digitally signed document containing the user's identity and attributes.

The SAML assertion is passed to AWS through the AssumeRoleWithSAML API call. This API call includes the Amazon Resource Name (ARN) of the IAM role the user wants to assume, along with the SAML assertion. AWS verifies the SAML assertion's signature and attributes with the trusted IdP metadata.

If everything checks out, AWS issues temporary security credentials associated with the IAM role specified in the request. These credentials enable the user to access AWS services and resources according to the permissions defined in the IAM role's policies.

OpenID Connect Federated Access

OpenID Connect (OIDC) is a modern protocol built on top of OAuth 2.0 that allows applications to authenticate users. When users want to access AWS resources, they authenticate with their OpenID Connect-compatible IdP. The IdP returns an ID token, which contains the user's identity and other relevant information.

To enable federated access in AWS, you create an IAM identity provider that points to your OIDC IdP. Then, you create an IAM role with a trust policy that allows the OIDC identity provider to assume the role. Users initiate federated access by signing in through the IdP, and the OIDC token is exchanged for temporary AWS credentials through the AssumeRoleWithWebIdentity API call.

Web Identity Federated Access

Web identity providers include well-known platforms like Amazon, Facebook, Google, and more. These providers offer their own authentication mechanisms for user sign-ins. When a user authenticates with one of these providers, they receive an identity token.

Similar to OIDC, you establish an IAM identity provider for the web identity provider. You create an IAM role with a trust policy allowing the web identity provider to assume the role. Users authenticated by the web identity provider can assume the role using the AssumeRoleWithWebIdentity API call, receiving temporary AWS credentials to access resources based on the role's permissions.

Cross-Account Access

Traditionally, managing access to resources across different AWS accounts could be complex and potentially compromise security by sharing long-term credentials. However, AWS cross-account access with IAM roles simplifies this process while enhancing security and control. It empowers organizations to collaborate seamlessly, allowing users from one AWS account to access resources in another account with well-defined permissions.

This capability is particularly valuable for scenarios such as:

Organizational Collaboration: different departments, teams, or external partners can work together effectively by granting controlled access to specific resources.
Managed Services: organizations can centralize operations by providing external services, like managed security or analytics, and secure access to resources.
Consulting and Vendor Engagement: consulting companies or vendors can access client resources while adhering to stringent security practices.

The core concept behind AWS cross-account access is the utilization of IAM roles. Instead of sharing credentials, a trusted relationship is established between accounts. The trusting account defines an IAM role with a Trust Policy that allows IAM Identities in the trusted account to assume that role.

Let's say Account A (123456789012) wants to allow users from Account B (987654321001) to access specific resources. Account A creates an IAM role named CrossAccountRoleA and attaches a Trust Policy that specifies that Account B is allowed to assume this role.

Trust Policy for CrossAccountRoleA in Account A:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::987654321001:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {}
    }
  ]
}

In Account B (987654321001), IAM users or roles can assume the CrossAccountRoleA role from Account A (123456789012) because Account A has defined a trust policy allowing it. Users in Account B can use the AssumeRole API call to acquire temporary credentials for the CrossAccountRoleA role.

Assuming CrossAccountRoleA in Account B using AWS CLI:

aws sts assume-role --role-arn arn:aws:iam::123456789012:role/CrossAccountRoleA --role-session-name MySession

This will return temporary security credentials that can be used to access resources in Account A.

AWS Service-to-Service Access

AWS services often need to interact with each other for various purposes. For example, you might want an AWS Lambda function to access data stored in Amazon S3. Instead of relying on long-term credentials, you can create an IAM role with the required permissions and allow the Lambda function to assume that role. This enables the Lambda function to securely access the necessary resources without exposing sensitive credentials.

Here's a concise breakdown of how AWS Service-to-Service Access works:

Role Creation: create an IAM role with necessary permissions for an AWS service to perform specific actions on other AWS resources.
Trust Policy: specify the AWS service's ARN in the role's trust policy, allowing it to assume the role.
Role Assumption: the AWS service requests temporary credentials from AWS STS by assuming the role.
Temporary Credentials: AWS STS provides temporary credentials, including the Access Key ID, the Secret Access Key, and the Session Token.
Resource Access: the AWS service uses temporary credentials to interact securely with other AWS resources.

EC2 Instance Access without Long-Term Credentials

On 12 June 2014, Mike Pope announced a new, crucial AWS feature: Granting Permission to Launch EC2 Instances with IAM Roles.

If you deploy a workload on an EC2 instance that requires access to AWS services, instead of embedding IAM User’s long-term credentials (Access Keys) directly into the instance, which can pose security risks, you can assign an IAM role to it. This role grants temporary permissions to the EC2 instance, ensuring that the workload running on this instance can interact with AWS services securely without exposing credentials. This dynamic and controlled approach simplifies management and enhances security.

When creating the IAM Role that has to be attached to the EC2 instance, remember to add a Trust Policy that allows the trusted entity (in this case, the EC2 service) to assume the role. In particular, you’ve to add "Service": "ec2.amazonaws.com" as the Principal in the Trust Policy.

The IAM Role can be attached to the instance during its creation or when it is already running.

When you assign an IAM role to an EC2 instance, an instance profile is automatically created. This instance profile is associated with the IAM role and acts as a container for temporary security credentials. The instance profile is managed by AWS and is not directly accessible from outside the instance.

When an application or process running on the EC2 instance needs to access AWS services, it makes an HTTP request to the metadata service, which is a web service that provides information about the instance's configuration and attributes. In this case, the http://169.254.169.254/latest/meta-data/iam/security-credentials/<role-name> endpoint is invoked to retrieve temporary security credentials associated with the IAM role. These credentials include an Access Key ID, a Secret Access Key, a Session Token, and an Expiration Time. EC2 instances automatically renew the temporary credentials by periodically requesting updated credentials from the metadata service. This ensures uninterrupted access to AWS resources.

Interaction between IAM Users and IAM Roles

As far as now, we didn’t take into account any possible interaction between IAM Users and IAM Roles. Well, IAM users can interact with IAM roles through the process of assuming roles. This allows IAM users to temporarily take on the permissions and privileges associated with an IAM role, granting them access to resources they might not have direct permissions. This interaction is commonly used to delegate access to specific resources without sharing long-term credentials.

An IAM User initiates the process by calling the AssumeRole API, specifying the ARN (Amazon Resource Name) of the IAM Role they want to assume. The IAM User must have the necessary permissions to assume the role in the first place. These permissions are defined by an IAM Access Policy attached to the user. The IAM Role’s Trust Policy must contain a statement that allows the IAM User to assume it. If the trust policy allows the IAM User to assume the role, AWS STS (Security Token Service) generates temporary credentials for the IAM User. The IAM User can use the temporary credentials to make requests to AWS services just like they would with their own IAM User credentials. The IAM User only has the permissions associated with the assumed role, not their original IAM User permissions.

As previously mentioned, it is possible to enable MFA for an IAM User. In the user's Access Policy, you can define actions that require MFA protection. This means that these actions can only be performed using IAM User credentials that include MFA information.

To generate credentials that include MFA information, you must call the STS GetSessionToken API and provide a valid MFA token associated with a hardware or virtual MFA device. You can then use the resulting credentials to call MFA-protected actions.

When should I go for IAM Users and when for IAM Roles?

IAM Users

IAM Users are well-suited for managing access within your AWS account, particularly for individuals and applications that require straightforward access to AWS services and resources. They offer personalized access control and are appropriate for the following scenarios:

Individuals: If you have human users who need to interact with AWS services using the AWS Management Console, IAM Users provide a way to grant personalized access. You can assign permissions based on each user's roles and responsibilities.
Simple Application Access: For applications running within your AWS account that require programmatic access to AWS services, IAM Users can be used. However, it's important to note that IAM Roles are often a better choice for applications, as they provide temporary access without exposing long-term credentials.

While IAM Users are useful for straightforward access requirements, they might not be the optimal solution for scenarios involving temporary access, cross-account access, or enhanced security.

IAM Roles

IAM Roles offer a more comprehensive approach to access management, particularly when dealing with complex access patterns and security considerations. They are the recommended choice in the following situations:

Federated Access: When you need to grant temporary access to users from external identity providers (IdPs) such as SAML, OpenID Connect, or web identity providers, IAM Roles provide a secure way to authenticate and access AWS resources without exposing long-term credentials.
Cross-Account Access: IAM Roles excel at enabling secure collaboration between AWS accounts. This is crucial for scenarios like organizational partnerships, managed services, and consulting engagements.
Service-to-Service Access: IAM Roles facilitate secure interactions between AWS services without relying on long-term credentials. This enhances security and adheres to the principle of least privilege.

IAM Roles streamline security, minimize long-term credential exposure, and provide controlled access. They're designed to address a wide range of security and access requirements.

In summary, while IAM Users are suitable for simpler access scenarios within an AWS account, IAM Roles offer a more advanced and secure approach for managing complex access patterns, temporary access needs, and cross-account collaboration. The choice between IAM Users and IAM Roles should align with the specific security requirements and complexity of the access scenario you're addressing.

That’s all Folks!

In this blog post we have seen what are IAM Users and IAM Roles, what are the differences between them, and the use cases in which they’re used.

I hope you enjoyed this blog post and that you find it informative. Please, don’t hesitate to provide your feedback and share your thoughts about the topic. Feel free to reach out to us on our Community Slack!

Stay tuned for new publications!

Who am I in AWS? Presenting IAM STS get-caller-identity

Eric Villa — Thu, 01 Jun 2023 15:44:29 +0000

Have you ever been in a situation in which you were about to forward a critical API request to AWS but you were not sure what was the target of your request?

It’s always a best practice to check if the API request target is the one that you expect, especially if the operations that are about to be performed may have major repercussions on your AWS accounts.

Who am I in the context of AWS?

When it comes generate temporary credentials and get information about them, AWS Security Token Service (AWS STS) comes to the rescue.

“Who am I in the context of AWS” is exactly the question the AWS STS GetCallerIdentity API provides an answer to. The answer tells you what is the account affected by the next API call if credentials are not going to change in the meanwhile.

Yes, I mentioned AWS STS. Indeed, this is the service that I should call upon to get that information. To interface with the GetCallerIdentity API, two requirements must be fulfilled:

network connectivity;
a valid set of AWS Credentials, placed in one of the locations the client that you’re using expects them to be (environment variables, shared configuration files, etcetera). As you can see on this documentation page, authentication information is added to the request via the Authorization Header.

The reference client used in this article is the AWS CLI (Command Line Interface). The AWS CLI command that you should issue to get this information is the following:

aws sts get-caller-identity

aws sts get-caller-identity response structure

Regardless of the IAM identity used to authenticate the request, the API response always contains three fields:

UserId - the unique identifier of the calling entity;
Account - the AWS Account ID number of the account that owns or contains the calling entity;
Arn - the Amazon Resource Name associated with the calling identity.

While the Account field is always a 12-digits number, Arn and UserId depend on the principal that initiated the request.

In this blog post, we’ll focus on two categories of principals: User and AssumedRole.

The User category simply corresponds to the IAM User principal.

The AssumedRole category covers more principals, but we’ll focus on SAML federated user (assumed via AssumeRoleWithSAML API), assumed role (assumed via AssumeRole API), and role assigned to an Amazon EC2 instance.

For a complete overview of principals, please refer to the documentation.

Now, let’s deepen the UserId and Arn fields for each of the previously cited principals.

IAM User

{
    "UserId": "AIDACKCEVSQ6C2EXAMPLE",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/JohnDoe"
}

The UserId corresponds to the unique ID of the IAM User.

The Arn field adheres to the following template: arn:aws:iam::<account-id>:user/<user-name-with-path>.

SAML federated user

{
    "UserId": "AROACKCEVSQ6C2EXAMPLE:johndoe@example.com",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/john.doe/johndoe@example.com"
}

The UserId consists of the unique ID of the role (AROACKCEVSQ6C2EXAMPLE) and the caller specified role name (johndoe@example.com).

The caller specified role name corresponds to the RoleSessionName attribute that is part of the SAML assertion.

The SAML assertion is an authentication response forwarded by the external IdP to the https://region-code.signin.aws.amazon.com/saml endpoint. The SAML assertion contains a set of claims; the RoleSessionName is one of them.

Typically, the value of the RoleSessionName attribute is a user ID or an email address. As explained in this blog post by my fellow colleague Nicolò Marchesi, when it comes to federating a G Suite IdP to an AWS account, the RoleSessionName SAML attribute is mapped to the G Suite user’s Primary Email.

The Arn field adheres to the following template: arn:aws:iam::<account-id>:assumed-role/<role-name>/<role-session-name>. The Principal Type is not a user - as for the IAM User - but an assumed-role. Indeed, the SAML-based federation allows a user - managed by the external IdP - to assume an AWS Role via the STS assumeRoleWithSAML API.

Assumed role

This principal corresponds to an IAM Role assumed via the AssumeRole API. Using this API, an IAM Role can be assumed by either an IAM User, an AWS IAM Identity Center user, or another IAM Role (the last configuration is called role chaining).

All these configurations provide the same GetCallerIdentity API response structure.

{
    "UserId": "AROACKCEVSQ6C2EXAMPLE:FakeRoleSessionName",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/FakeRoleName/FakeRoleSessionName"
}

As for the SAML federated user scenario, the Arn field adheres to the following template: arn:aws:iam::<account-id>:assumed-role/<role-name>/<role-session-name>.

The UserId field is composed of the unique id of the role and the caller specified role name that is specified by the RoleSessionName parameter passed to the AssumeRole request.

Role assigned to an Amazon EC2 instance

When you launch an Amazon EC2 instance, you specify an IAM role to associate with the instance. Applications that run on the instance can then use the role-supplied temporary credentials to sign API requests. To be precise, the IAM Role is encapsulated in an Instance Profile which can provide the role’s temporary credentials to an application that runs on the instance.

When you call the AWS STS GetCallerIdentity API, the request is signed using the temporary credentials supplied via the Instance Profile. The following is an example response.

{ "Account": "123456789012", "UserId": "AROACKCEVSQ6C2EXAMPLE:i-1234567890abcdef0", "Arn": "arn:aws:sts::123456789012:assumed-role/iam-role-name/i-1234567890abcdef0" }

The UserId field is composed of the unique id of the role (AROACKCEVSQ6C2EXAMPLE) and the unique identifier of the EC2 instance (i-1234567890abcdef0).

The Arn field adheres to the following template: arn:aws:iam::<account-id>:assumed-role/<role-name>/<role-session-name>. The corresponds to iam-role-name while the corresponds to the unique identifier of the EC2 instance.

That’s all Folks!

In this blog post, I’ve provided you with a description of the API that you can consume to answer the question “Who am I in the context of AWS?”. The answer to that question can vary, depending on the Principal associated with the IAM Credentials used to sign the GetCallerIdentity API.

Reach out to me, if you want to enrich the list of most common scenarios where you can find yourself in.

Stay tuned for new publications!

Fixing botocore.exceptions.nocredentialserror: unable to locate credentials [SOLVED]

Eric Villa — Mon, 06 Mar 2023 16:25:48 +0000

If you saw this error while running a Python script or application, you stumbled upon one of the most common errors that arise when boto3 is unable to locate valid AWS credentials needed to sign an API call to a specific AWS service.

There are many StackOverflow questions about that:

This error is specific to Python; if you’re looking for a solution to the “Unable to locate credentials” issue we’ve already written a blog post about that.

Before calling an API, you need to create a client specific to the service you want to use.

The most traditional way to instantiate a service client consists in using one of the following abstractions provided by the boto3 SDK:

boto3.client('s3');
boto3.resource('s3').

Regardless of the type of abstraction, a new default boto3.session.Session is created unless another one is already instantiated. If you are wondering what a boto3.session.Session object is, I suggest referring to its documentation:

A session stores configuration state and allows you to create service clients and resources.

A simple example

To reproduce the error, let me use an example script that invokes the Amazon S3 API that returns the list of all buckets owned by the authenticated sender of the request.

import boto3

s3_client = boto3.client("s3")

list_buckets_response = s3_client.list_buckets()["Buckets"]
bucket_names = ", ".join(list(map(lambda bucket: bucket["Name"], list_buckets_response)))

print(bucket_names)

As I previously said, when boto3.client("s3") instruction is executed, and a new default session object is created; this session object wraps AWS credentials info too. You can easily deduce that if boto3 is not able to locate credentials, the botocore.exceptions.NoCredentialsError error is thrown. In this scenario, executing the previous script will produce an output similar to the following:

Where is boto3 looking for credentials?

boto3 searches for AWS credentials through a list of possible locations until it finds valid ones.

As described in the documentation:

Boto3 gives higher priority to credentials passed as parameters during client initialization.
If credentials are not provided this way, it looks for them inside environment variables and shared configuration files (i.e., ~/.aws/credentials and ~/.aws/config files).
If it’s still unable to get valid credentials, it tries to obtain them through the Instance Metadata Service on an Amazon EC2 instance with an IAM role configured.

Again, botocore.exceptions.NoCredentialsError is raised if boto3 is unable to find valid AWS credentials in any of the listed locations.

Let's find a solution!

To solve the issue, I’ll generate a set of temporary credentials associated with a specific IAM User. Generating temporary credentials for an IAM User involves calling the STS get-session-token API. I let Leapp generate them automatically for me.

Once set up, boto3 should be able to obtain valid AWS credentials from the ~/.aws/credentials file. Let’s try running the Python script again.

As expected, boto3 found a valid set of temporary credentials in the ~/.aws/credentials file. It used those credentials to sign the Amazon S3 API request and obtain the list of buckets owned by the authenticated sender of the request.

Boto3 Session: The Icing on the Cake

What about long-running scripts? What if the script tries to access the Amazon S3 list bucket API, but the first set of credentials loaded by boto3 is expired? Well, it will not be able to forward the request.

The problem is that using only boto3.client or boto3.resource module-level functions, the first set of credentials is wrapped into a default boto3.session.Session object that will not be refreshed.

To keep credentials always aligned with those found in one of the Credentials Provider Chain locations, you can instantiate a boto3.session.Session objects directly and obtains new Amazon S3 clients from it as follows.

import boto3

while True:
  input("type a key to list the available Amazon S3 buckets")

  s3_client = boto3.session.Session().client("s3")

  try:
    buckets = s3_client.list_buckets()["Buckets"]
    bucket_names = ", ".join(list(map(lambda bucket: bucket["Name"], buckets)))
    print(bucket_names)
  except Exception as e:
    print(e)

To emulate a long-running script, I introduced a while loop that starts by asking the user to type a key to run the n-th iteration. That way, we can control credentials availability by starting/stopping the Leapp Session before the n-th iteration is triggered.

At this point, let’s run the script by leaving the Leapp Session stopped; it returns the following output.

As you can see, it was unable to locate credentials as, at the time the 1st iteration was triggered, credentials were not available in any of the Credentials Provider Chain locations.

And now, let’s start the Leapp Session.

At this point, a new set of temporary credentials associated in the ~/.aws/credentials file.

By triggering the 2nd iteration, we got the following output from the script:

During the 2nd iteration, boto3 was able to instantiate a new Session object from a valid set of AWS credentials located in the ~/.aws/credentials file. Therefore, it could sign and forward the request to the Amazon S3 bucket endpoint to obtain the list of buckets owned by the authenticated sender.

I can fine-tune the previous script to maintain a single instance of the Session object and re-instantiate it only if the credentials used to sign the request are expired.

So, my suggestion is to use the boto3.session.Session objects, as instantiating, is an elegant way to refresh credentials.

That’s all, Folks!

I hope you found all the information you needed to understand and solve the botocore.exceptions.NoCredentialsError!

As a takeout, consider refactoring your existing code to adopt the boto3.session.Session object unless you are already using it. It could be a game-changer, especially in long-running scripts.

This article is part of this blog's “IAM how to fix” series.

Stay updated with your IAM expertise by subscribing to our newsletter!

Share your thoughts and feedback about this blog post in a comment or by reaching out to me through my Twitter profile.

If you liked the Leapp experience, give us a star!

What are AWS credentials?

Eric Villa — Tue, 17 Jan 2023 14:39:16 +0000

John: “Hey Eric, I need to access project-xyz dev account! Can you help me in some way?”

Me: “Sure, but what kind of access do you need?”

John:

Dear John, there are two kinds of access to AWS:

via Web Console;
programmatic.

Web Console access

This type of access requires you to log into your AWS account using your preferred browser.

When I set up my first AWS account, I logged into it as a root user using my browser. The first thing I did was create a brand new admin IAM User and enable Web Console access for it.

Why? Because managing root user credentials is too dangerous, as you can’t disable them once stolen… get it? So, use them to create an admin IAM User, store them in your password manager, and simply forget about them.

Let me share with you two docs:

In 2018 AWS introduced AWS Organizations, a service that lets you consolidate and centrally manage multiple AWS Accounts. It is a best practice to govern access to these accounts through AWS Organizations’ preferred buddy: AWS SSO.

AWS SSO lets you create and manage a dedicated pool of users unless you want to federate it with an external Identity Provider.

Users can access the AWS Management Console via the so-called Portal URL, which looks similar to the following one:

d-012345dee0.awsapps.com/start

For sake of completeness, let me add SAML 2.0 federated access to the previously described ways of accessing an AWS account from the Web Console.

If you want to dig into SAML 2.0 federated access to AWS, give a look at this blog post by my fellow colleague Nicolò Marchesi.

And now… Ladies & Gentlement, programmatic access!

Programmatic access

When you talk about AWS credentials, you probably refer to this kind of access, not the Web Console-based one.

Well, as you might guess, AWS credentials are included in the browser too when accessing an AWS account via Web Console; yes, through dedicated HTTP cookies.

What does programmatic access actually mean?

Programmatic access refers to accessing an AWS account by the means of a client, i.e. an AWS SDK or the AWS CLI.

These clients rely on AWS credentials to add authentication information to the HTTP calls sent to AWS APIs. Without this information, AWS won’t allow you to access your account. In particular, the AWS credentials we’re referring to are called Access Keys.

Access Keys

So, Access Keys are AWS credentials used by AWS SDKs or by the AWS CLI to add authentication information to programmatic HTTP calls sent to AWS APIs.

There are two types of Access Keys out there: long-term and temporary ones.

Long-term credentials are the ones that are bound to a specific IAM User. Long-term credentials do not expire; therefore, as a best practice, it is warmly recommended to rotate them regularly.

On the other hand, temporary (or short-term) credentials are time-limited; therefore, if they’re associated with an IAM permission that is designed with Least Privilege in mind, they reduce your AWS account/s exposure to attackers.

Be careful: sometimes applying these best practices is not enough to prevent privilege escalation.

Where can Access Keys be found?

The answer to this question is quite simple. Access Keys can be found in all those places where the clients are programmed to look credentials for. These places (or sources) are mapped into the Credentials Provider Chain, as explained in this blog post.

In your local environment, Access Keys are commonly stored in the ~/.aws/credentials file or exported as Environment Variables.

As a best practice, ~/.aws/credentials should be used to contain only Access Keys, while configuration information should be specified in the ~/.aws/config file.

If you’re using Environment Variables as the source of the credentials, Access Keys are exposed using the following Environment Variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and - for temporary credentials - AWS_SESSION_TOKEN.

What do they look like? A glance into ~/.aws/credentials file

If you already had the opportunity to peek at the ~/.aws/credentials file, I’m quite sure you found content similar to the one illustrated in the screenshot above.

Well, there is no need to explain what the aws_access_key_id, aws_secret_access_key, and aws_session_token keys refer to… but there are some interesting considerations we can make about aws_access_key_id value (ASIA2JPYALK…).

The first four letters of the aws_access_key_id key identify the credentials type. The ASIA prefix, which you can see in the screenshot, tells us that the credentials are temporary ones, i.e. an aws_session_token is involved. These temporary credentials are generated through the AWS Security Token Service.

If the aws_access_key_id starts with AKIA, it means that we’re dealing with long-term credentials; in this case, the aws_session_token is not needed.

~/.aws/credentials is a .ini file. In the screenshot, you can notice a [default] header before the aws_access_key_id key. The string contained in the square brackets defines the Named Profile the Access Keys are wrapped into. The Named Profile is a container that groups secrets and configuration information associated with a set of AWS credentials. As we said before, the credentials file is designed to contain only credentials; configuration information, associated with the default Named Profile, should be specified in the ~/.aws/config file, under the [default] header, as for the credentials file.

Note: you can use multiple Named Profiles at the same time. The default Named Profile is the one used by clients if you don’t provide them with the Name Profile you want to use. For example, the AWS CLI will use the default Named Profile if you don’t specify the --profile flag or if its value corresponds to default.

Stop wrestling with AWS credentials

If you’re wondering if there is a tool that allows you to stop thinking about AWS credentials and where to store them in the right way, give a look at Leapp! It takes the responsibility of storing long-term credentials in the system vault, generating/refreshing short-term credentials, and placing them in the right place for the clients to use them.

That’s all Folks!

If you’re new to AWS credentials, I hope you find this blog post a smooth introduction to them. If your curiosity is not yet satisfied, you can unwrap the next gift.

AWS Credentials: from Environment Variables to credentials_process

Eric Villa — Thu, 01 Dec 2022 17:33:08 +0000

If you need to clarify what are the different kinds of AWS Credentials available, how they’re generated, what they’re used for, and what are the best practices to manage them in a proper way, I think you landed in the right spot!

Spoiler: we’re going to focus on programmatic access to AWS resources and/or services. Programmatic access means making programmatic calls to AWS via one of the available SDKs or by using the AWS Command Line Interface.

First of all, let’s start from a term: Principal. For those who never heard it, let me quote the AWS Docs for you:

A principal is a person or application that can make a request for an action or operation on an AWS resource.

Every time you try to call an AWS API, you’ll meet a guardian on your way: the AWS IAM authentication, which authenticates AWS API requests.

The Principal authenticates himself as a root user or as an IAM entity, i.e. an IAM User or an IAM Role. A common best practice is to avoid using root user credentials; Instead, prefer IAM entities.

AWS IAM is able to authenticate API requests only if the required authentication information is present in the payload. This authentication information is represented by a signature that is added to the API request in one of the following forms: HTTP Authorization header or Query string parameters. The signature is calculated through a mechanism called AWS Signature Version 4 (SigV4), which uses the Access Keys associated with an IAM entity.

So, what are Access Keys? Access keys are IAM entity-bound credentials used by clients to sign API requests for programmatic access.

A client can be either the AWS CLI, AWS Tools for Windows Powershell, AWS SDKs, or an application that implements the SigV4 logic needed to add authentication information to the API requests. If you are implementing an application that interfaces with AWS resources, my suggestion is to avoid reinventing the wheel and rely on the SigV4 logic already encapsulated in the AWS SDKs, unless you have to satisfy particular needs.

The Credential Provider Chain

As I stated before, SigV4 uses Access Keys to compute the signature of an API request. Therefore, the previously described clients need to gather these credentials from somewhere, before the API request is actually signed and sent. In particular, clients follow a systematic approach to search credentials in a pre-defined set of sources. This approach is called Credential Provider Chain. The list of sources may vary depending on the specific AWS SDK, so let’s focus on the main ones:

environment variables;
Web Identity Token credentials;
the shared config and credentials files;
Amazon ECS container credentials;
instance profile credentials.

It is a chain in the sense that, starting from the first source in the list, the client checks for the presence of credentials; the search stops as soon as a valid set of credentials was found.

Long-term and temporary credentials

Before diving into the different sources available in the Credentials Provider Chain, it is important for you to know that there are two different kinds of credentials for programmatic access: long-term and short-term (or temporary) ones.

Long-term credentials consist of an access key id and a secret access key, also called access keys. You can think of the access key id as the username and the secret access key as the password. Long-term credentials allow you to access and authenticate yourself as a root user of an IAM User inside an AWS account.

Short-term credentials come with two additional members: a session token together with an expiration time. Yes, because short-term credentials expire after a while, as specified in the expiration member. The main actions used to retrieve short-term credentials are the following:

Each of these actions is associated with a different access method, i.e. the pattern followed to perform a specific AWS action, in a specific AWS account, as a specific AWS IAM Entity (AWS IAM User or AWS IAM Role). We’ll focus on access methods when talking about shared config and credentials files, as these two topics are tangent.

In the meanwhile, let me point out that it’s a best practice to prefer short-term credentials to long-term ones, as they limit the time window available to an attacker - who stole them - to perform malicious actions against your AWS resources.

Both types of credentials can be rotated: for what concerns long-term access keys, rotating them means creating a new key pair (access key id + secret access key) associated with an IAM User and deleting the old one. On the other hand, rotating short-term credentials means creating new ones and exporting them to one of the available Credentials Provider Chain sources. To be precise, there is an exception: you don’t have to take charge of generating and rotating Amazon ECS container and instance profile credentials, as they’re sourced from an HTTP endpoint.

Now that you’ve an idea of what long and short-term credentials are and what are the main differences between them, let’s dive into Credentials Provider Chain sources, starting from the environment variables, as they’re the first place clients look for credentials.

Credentials source - environment variables

Simply put, to make a client aware of credentials as environment variables, you have to set the following ones:

AWS_ACCESS_KEY_ID;
AWS_SECRET_ACCESS_KEY;
AWS_SESSION_TOKEN.

The AWS_SESSION_TOKEN environment variable should be set only for temporary credentials.

Credentials source - shared config and credentials file

If the client does not find valid credentials in the previously cited environment variables, it shifts the focus to the shared config and credentials file.

The shared config and credentials are .yml files located under the ~/.aws folder.

Each of these files has its own purpose, even if it is not always respected. In particular, the config file is designed to keep configuration data, which is not sensitive; on the other hand, the credentials file is designed to keep secrets. These responsibilities are not respected when we find secrets in the config file and configuration data in the credentials file.

When you run a command from the CLI, it is executed under the scope of a specific Named Profile. A Named Profile is a container for a specific set of configuration data and secrets. Following the best practice cited before, a Named Profile could span both config and credentials files.

In the credentials file, a Named Profile can wrap the following secrets:

aws_access_key_id;
aws_secret_access_key;
aws_session_token (only for temporary credentials).

In the config file, for each Named Profile, you can specify configuration data that allows you to describe the access method or, in simple terms, the pattern used to access services and resources in an AWS account. The AWS account the request is forwarded to depends on the IAM entity (IAM User or IAM Role) you are authenticating as.

The IAM User access method

The first access method that comes through my - and maybe your - mind is the IAM User. Accessing an AWS account as an IAM User means providing at least aws_access_key_id and aws_secret_access_key to the ~/.aws/credentials file. I said “at least” because you can get temporary credentials from an IAM User too, using the sts:getSessionToken action. In this case, the Named Profile - associated with the IAM User - should contain the aws_session_token secret too. In this scenario, in the config file, I would put only the region and output fields. Please, remember to put them under the same Named Profile as the one used in the credentials file.

The Assume Role access method

The second access method I want to describe is the one that expects an IAM Role to be assumed by another IAM entity. You can describe this access pattern in the shared config file using the following two Named Profile fields: source_profile and role_arn.

The source_profile corresponds to the Named Profile that wraps the configuration data and secrets associated with the assumer IAM entity.

The role_arn corresponds to the ARN of the IAM Role that is going to be assumed. You’ve to remember to set up a trust relationship between the assumer and the assumed IAM entities, but that’s another story.

Using this access method, when you run an AWS CLI command using the Named Profile associated with the assumed IAM entity, the CLI generates temporary credentials using the sts:assumeRole action and caches them for future uses under the ~/.aws/cli/cache folder. These cached credentials are refreshed as soon as a new AWS CLI command is run after the temporary credentials expiration time.

You can even chain multiple Named Profiles using this access method.

When it comes to assuming a role, it is possible to provide an additional authentication info, called external ID. The external ID is a token, shared between the AWS IAM entity and the client that wants to assume it. This token is designed to overcome the Confused Deputy problem (https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). You can specify the external ID in the Named Profile external_id field under the config file.

Another important configuration data that you can add to your Named Profile is the mfa_serial, if associated with the IAM User that is going to assume the IAM Role.

When you have to configure access to multiple AWS accounts using the Assume Role access pattern, it becomes difficult to get rid of all the Named Profiles configuration data and relationships. When you’ve to deal with a complex access scenario, tools like Leapp (https://www.leapp.cloud) come to the rescue! Leapp avoids you to specify relationships between Named Profiles in the config file, as the access methods are stored in the tool-specific configuration file.

Let’s now move to AWS SSO!

AWS SSO access method

To configure access to a specific IAM Role in an AWS account by the means of AWS SSO, you’ve to provide the following configuration data in the Named Profile.

sso_start_url: the portal URL used to authenticate your client against AWS SSO (uses OIDC authentication)
sso_region: the region in which AWS SSO was configured
sso_account_id: the ID of the AWS account that I want to access
sso_role_name: the name of the role that is going to be assumed in the AWS account
region: the region used by API requests

AWS CLI v2 supports AWS SSO and allows you to log into it through the following command:

aws sso login --profile <named-profile>

This command starts an OIDC authentication flow that requires the user to interact with the browser by providing an authorisation code and granting credentials for the AWS CLI. At this point, the CLI will receive an AWS SSO access token that is cached under the ~/.aws/sso/cache folder. This access token is then used by the CLI to invoke the sso:getRoleCredentials action. The new set of temporary credentials is then cached under the ~/.aws/cli/cache folder, as for the Assume Role access method, described before.

Instead of manually configuring a multitude of Named Profiles associated with different AWS SSO assumable IAM Roles, you can specify your AWS SSO configuration data in Leapp; once logged into AWS SSO, it allows you to automatically provision all the IAM Roles that you can access (you as the AWS SSO authenticated user).

Last but not least: the credentials_process

credentials_process is a cool feature that allows clients to generate temporary credentials by the means of a third-party CLI or command. The credentials_process is a configuration data field that should be defined in the shared config file, under a specific Named Profile. Using this mechanism, you don’t have to specify credentials in other places, as the credentials_process command becomes the credentials source.

It is important to make the credentials_process command return the temporary credentials in the following format.

{
  "Version": 1,
  "AccessKeyId": "an AWS access key”,
  "SecretAccessKey": "your AWS secret access key”,
  "SessionToken": "the AWS session token for temporary credentials”,
  "Expiration": "ISO8601 timestamp when the credentials expire"
}

credentials_process comes in handy in particular situations that are not supported out of the box by the shared configuration and credentials files. An example is the sts:assumeRoleWithSAML action, which requires the user to authenticate against an external SAML IdP; once the user is authenticated, the custom script should intercept the SAML Assertion returned at the end of the SAML 2.0 authentication. Then, this SAML Assertion will be included in the sts:assumeRoleWithSAML API request.

Leapp allows you to configure how you want to generate credentials. By specifying “credential-process-method” in its “AWS Credential Generation” setting, you’re able to make Leapp generate temporary credentials by the means of its CLI through the credentials_process field.

That’s all Folks!

I hope you enjoyed this article and that you found interesting tips to improve your AWS CLI configuration and credentials file management.

If you want to share your thoughts about this article or, more in general, about AWS Credentials management, please reach out to me through my Twitter profile.

We didn’t cover every aspect of the Credentials Provider Chain, so stay tuned for new articles about credentials generation in a local or remote environment!

Cheers

AWS is only as safe as the weakest credentials setup for your developers.

Eric Villa — Tue, 03 May 2022 14:11:22 +0000

A matter of prevention and mitigation

If you’re reading this article, you’re probably concerned about protecting your AWS assets from attackers, whether they’re human or machines. We will focus on how to prevent or, at least, reduce the opportunity of damage if the local cloud credentials are compromised.

AWS is a public cloud provider whose services are scriptable. This means you can easily provision resources, decommission them, or perform any other action with side effects on your AWS account.

Requests authentication

I refer to the action as an HTTP API call. HTTP API calls need to be signed through a process called Signature Version 4, which adds a signature to the HTTP request in a header or as a query string parameter; this allows requests to be authenticated.

You can implement the Signature Version 4 process by yourself, but it is a common best practice to use existing and validated solutions, like AWS SDKs, regardless of the programming language you’re using (as long as it is supported). If you’re not implementing an application and you need access to AWS API from the command line, the AWS CLI is the way to go.

AWS SDKs and AWS CLI are two examples of dev tools used to access AWS services through its authenticated API, but you can find more of them, like the AWS Toolkit for Visual Studio. All these dev tools encapsulate the SigV4 signing process described before. The signing key used to create SigV4’s signature is derived from an access key, i.e. your security credentials. If you’re dealing with short-lived security credentials, the API request contains the session token that you received from AWS STS.

I’m quite sure most of you are already aware of how dev tools seek AWS Credentials locally, in your machine, but I don’t want to take it for granted.

The Credentials Provider Chain

Both AWS CLI and SDKs look for security credentials following a Credentials Provider Chain.

From a local point of view, the main links of this chain are environment variables and shared configuration files. Basically, environment variables take precedence over the shared configuration files. If environment variables are not set, dev tools search for credentials in the $HOME/.aws/credentials file; lastly, they seek credentials in the $HOME/.aws/config file. The last one is not thought to be used as a container of sensitive information, but you can use it for this purpose. You can even use a third-party tool to generate credentials on demand by specifying the credentials_process key in the $HOME/.aws/config file.

Where can AWS credentials be found LOCALLY?

It should be clear that, if someone wants to get access to our cloud assets from a compromised machine, the main targets are the environment variables and the shared configuration files, but they’re not the only ones.

Based on the tools you’re using on your machine, there could be other places where an attacker can find sensitive information. For example, the attacker could find AWS credentials in one of your application’s codebases, regardless if they’re ignored by your version control tool (if you rely on git, use .gitignore file).

An unnoticed yet noteworthy place where credentials could be found in the command history, accessible from both Linux and macOS machines. Imagine you exported long-term credentials as environment variables using the export command; well, this sensitive information will be kept in the history until you clear the command history.

Another place where the attacker can find sensitive information that can damage not only tour AWS accounts is your password manager, whether you’re using it as a browser extension or desktop app. If the login is not expired, the malicious person (or software), can steal critical AWS credentials. For example, as a security best practice suggested by AWS, you may have stored your root account credentials in your password manager. If root account credentials are stolen, you have only one option left: contact AWS to close your account.

Some local AWS credentials managers use the System Vault, e.g. macOS Keychain, to store long-term AWS credentials that are used as a baseline to generate short-term ones. The System Vault is another local asset that can be compromised by an attacker to grab AWS credentials that can be exploited to damage your AWS accounts.

The ones described above are examples of the common places where an attacker can find sensitive information. You can still find them in custom places; for example, for what concerns AWS shared configuration files, you can set a custom location for both credentials and config file exporting, respectively, AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE environment variables.

How can your machine be compromised?

Be careful when configuring access to your personal or work laptop. It is always recommended to use a strong password to protect it from being compromised. In the best scenario, some of your nice colleagues can introduce some funny jokes in your development environment (not that funny for you)!

Another important point that is sometimes neglected consists in your disk encryption. By encrypting it, you avoid anyone to access its content unless it is unblocked with your login password.

And what if I have full control of my laptop? Can something still happen? Well, as stated before, the attacker can be either a human or software. If I’m not aware of malicious software installed on my laptop, it could exploit vulnerabilities exposed by unpatched legit software. An interesting case of malicious software that is deployed with the purpose of stealing AWS Credentials is the TeamTNT Script. In this case the malicious scripts are not thought to run on developer’s laptops but on AWS EC2 instances and AWS ECS containers. It steals AWS credentials via their meta-data URLs (169.254.169.254 for AWS EC2 and 169.254.170.2 for AWS ECS), as well as environment variables from Docker systems.

Shared Responsibility Model

Before diving into some strategies to mitigate AWS credentials theft, let’s make a small digression on the Shared Responsibility Model.

In a nutshell, AWS is responsible for the security of the cloud, not the security in the cloud. This means that AWS operates the security of hardware, software, networking, and facilities that run AWS Cloud services. On the other hand, the AWS user is responsible for selecting and configuring services and resources in the cloud, in his AWS accounts. This includes configuring Identity and Access Management following best practices. Identity and Access Management configuration affects what an IAM principal can do on what resource and under what condition. I find it useful to have a detailed overview of IAM Policy Evaluation logic because it gives an idea of the authorization flow of an authenticated HTTP API call.

Policy Evaluation flow chart

AWS credentials theft mitigation strategies

Let's go through some of the best practices to reduce the opportunity of damage if the local AWS credentials are compromised.

1 - Do not use root account credentials

Root account credentials should be used only during the initial AWS account set up to create an AWS IAM User with administrator privileges. Then, root account credentials should be kept safe in your password manager, e.g. LastPass or Bitwarden. Distributing root credentials is extremely dangerous as you cannot invalidate them once stolen.

2 - Enable MFA, everywhere!

Whether you’re logging into AWS through a SAML federation or through IAM User credentials, enabling Multi-Factor Authentication adds a layer of security to the login process. Basically, it requires the user to specify a code in addition to the basic login information. The code can be generated either by a virtual device (e.g. Google Authenticator application) or a physical one (e.g. YubiKeys). Remember that, when using AWS role chaining feature, MFA information is carried only in case of an MFA-enabled IAM User that assumes a role that requires MFA information to be forwarded in the assumeRole API call.

Passing MFA information from the AWS CLI could be cumbersome, but you can use Dev Tools like Leapp to simplify the flow.

I suggest not to use MFA authenticator plugins for the browser. If you’re logged into a password manager, having an MFA authenticator plugin installed in the browser basically broke the knowledge + possession mechanism, as the second factor (the MFA code) can be retrieved from your laptop, together with the basic authentication info gained through the password manager.

3 - Prefer short-term credentials

As you know, AWS allows you to sign HTTP API requests with both short-term and long-term credentials.

When using long-term credentials you must be aware of the fact that, to be used by dev tools, they should be placed in one of the unencrypted locations that are part of the Credential Provider Chain. If someone stoles these credentials, they’re not limited by credentials expiration time. An example of long-term credentials is the AWS IAM User access key.

On the other hand, using short-term credentials reduces the blast radius of a credentials theft. Remember that short-term credentials’ duration range varies from one access strategy to another: short-term credentials generated from an IAM User access key have a duration that ranges from 15 minutes to a maximum of 36 hours; short-term credentials generated through the assumeRoleWithSAML and assumeRole APIs have a duration that ranges from 15 minutes to a maximum of 12 hours.

4 - Rotate credentials

It is a best practice to rotate credentials regularly, even if they’re short-lived ones. In this context, having a background process that refreshes them periodically makes the difference, as you don’t have to do it manually every time they expire.

5 - Apply the Principle of Least Privilege

I want to point it out, even if this is not something you can do locally without accessing your AWS accounts.

Credentials that are managed in your local machine always refer to an IAM Principal that has some kind of access privileges in your AWS accounts.

What you can do inside these accounts depends on - at least - how access policies, resource policies, and service control policies were set (probably by someone who’s responsible for the security of your organization). That’s critical for the security of your cloud assets that every IAM Principal has a set of permissions tailored to its role inside one or more workloads. Following this best practice mitigates the damage in case of credentials theft and, in general, provides guardrails for human error-prone tasks.

6 - Use of the external id

In abstract terms, the external ID allows the user that is assuming the role to assert the circumstances in which they are operating. It also provides a way for the account owner to permit the role to be assumed only under specific circumstances. The primary function of the external ID is to address and prevent The confused deputy problem.

external id is something that must be provided by those who want to access a specific IAM Role. The only requisite is that the role has a trust policy that contains a condition with the sts:ExternalId key. It becomes critical when trusting a third-party application as a "deputy" that can act on your behalf.

7 - Don’t store secrets in your source control

When working on a project is fairly common to have one or more secrets in your project’s folder, typically for running your application locally, digitally signing your executable, launching a pipeline, connecting to your Cloud Provider, and so on.

These secrets are a possible source for an attack, and there are many malevolent bots on the Internet that regularly scan public repositories like those on GitHub (they are public and accessible by everyone), or even incorrectly configured S3 buckets (wrong permissions, public access) to find secrets for exploiting accounts or services.

Point is, always ignore secrets in your .gitignore files, or even better, try to store and retrieve them programmatically from secure vaults, like your System Vault or services like AWS Secret Manager.

8 - Patch and upgrade your OS regularly

It’s very important to understand that every day new exploits or vulnerabilities are found for many software or even inside OS code that can be potentially exploited to gain access to your System, retrieve sensible information, and maliciously act on your behalf. This is especially true when you are a Developer and have tools like npm installed.

The more an application contains heavily used third-party libraries, the highest are the chances to be exposed to a vulnerability.

To avoid being exposed to vulnerabilities, always strive to keep your software and OS patched and upgraded.

Keep an eye on building warnings when compiling your solution, and check your npm messages when installing a new library. Upgrade them when needed.

If you are storing your project on GitHub verify your DependaBot messages, they usually contain precious information about vulnerabilities found in your codebase.

Raise the security culture of your organization

As described in this blog post by Nathan Case, it is critical to be involved in the dev cycle, raise your organization’s awareness of security issue, best practices, and credentials theft prevention and mitigation strategies. Moreover, it’s important to encourage the usage of standard tools to uniform and facilitate the Developer’s processes. For what concerns the local AWS credentials management, Leapp comes to the rescue with its Desktop App and Command Line Interface. It defines a consistent way to manage your access configuration, keep sensitive information encrypted, and generate temporary credentials that can be used by Dev Tools, like the AWS CLI, to perform operations in the cloud.

That’s all Folks!

I hope you find this article useful to integrate some best practices into your daily workflow, and that it has provided an opportunity to reflect on some security issues that may affect your organization. Feedback and comments are always welcome, so don’t be shy and feel free to direct message me or reach out to our Leapp Slack channel.

Keep in mind that AWS is only as safe as the weakest credentials setup for your developers.

Azure access scenarios, from a DevOps point of view

Eric Villa — Thu, 25 Mar 2021 12:58:32 +0000

At a first glance, you may wonder what the "DevOps point of view" in the subtitle actually means.

I used this term to describe the idea behind this article, i.e. giving you an overview of some punctual access strategies that need to be put in place to allow DevOps to access resources and services hosted inside an Azure organization.

The way we design access strategies depends on different factors, e.g. the kind of operation that has to be fulfilled or the user type, whether it is internal or external to the organization.

I will focus the attention on two main types of tasks: operational and development ones.

By operational, I mean tasks that can be completed through the usage of the Command Line Interface or by accessing the Azure Console through a browser.

On the other hand, by development tasks, I mean running scripts or testing applications locally. In this scenario, we will see that the way an application accesses Azure resources may change from development to production environment.

Before describing these access scenarios, I'll take the opportunity to organize a little bit of the concepts around a complex service like Azure AD, by separating the notion of authentication from the one of authorization.

In particular, we'll cover mechanisms that represent the foundation of identities authentication, regardless they're internal or external to the resource hosting Azure organization.

For what concerns authorization, we'll go in-depth about Azure Role-Based Access Control, which governs who can access what resource, under what condition.

Summary

Azure authentication
- Azure Tenant and Azure AD Directory
- Is the User a Member or a Guest?
- Federation
  - Custom Domain Name federation
  - Direct Federation
- Service Principal and Managed Service Identities
Azure authorization: Role-Based Access Control
The "DevOps point of view": different access scenarios

Azure authentication

Azure Active Directory is Azure's cloud-based access management service that stores and manages identities, enabling access to Azure resources inside a single Azure organization or across multiple ones.

Azure Tenant and Azure AD Directory

When we refer to an organization, a company, or - in general terms - a domain, we use the notion of Tenant. As described in my previous blog post, a Tenant represents "the organization that owns and manages a specific instance of Microsoft Cloud Services", i.e. a specific Tenant manages one or many Microsoft Cloud Services subscriptions, from Microsoft Office 365 to Microsoft Azure; for the sake of this article, we will focus on Azure ones.

Each Tenant is associated with one and only one Directory, which represents the Azure AD service. An Azure AD Directory can manage and authenticate a pool of users that can access resources hosted in the same Tenant where the Directory lives.

Is the User a Member or a Guest?

Users stored in an Azure AD Directory can fall into one of the following categories: Member or Guest.

A Member User is an identity internal to the organization, while a Guest User is an identity that has been invited to collaborate into the organisation, i.e. a partner or a collaborator.

The Type is simply a property attached to a User but allows the definition and enforcement of type-based policies.

Figure 1.

As illustrated in Figure 1 - which is taken from Azure's Documentation - both Member and Guest Users may be homed in the organization's directory, in an external one, or even on-premise.

Guest Users is the synonym of B2B User. The default B2B collaborative model expects the B2B User to be invited into the organization's directory, while it is homed in an external one. This model allows guest users to authenticate using their own organization's credentials.

You can invite a User, homed in an external Azure AD Directory, as Guest User in your organization's Directory by sending an invitation email. This is not the only way to invite guest users, but it provides contextual information that allows them to accept the invite or not. To start accessing resources in your organization, a guest user needs to redeem the invitation email.

If you've to import multiple guest users in your organization's directory, you can exploit the bulk invite feature, but remember that it is in preview, so don't use it in full confidence!

So far, we talked about users that are internal or external to your organization, but always inside the scope of Azure AD. What if an external user belongs to an IdP that is out of Azure AD's scope? This is the situation in which federation with external identity providers comes to the rescue.

Federation

Federation is the process of setting up a trust relationship between an Identity Provider and a Service Provider. In the scenario that I'm describing, Azure is the Service Provider that has to be federated with an external Identity Provider, e.g. G Suite.

For what concerns Azure AD, federation with external IdPs can be established using different approaches and protocols.

IMO, the two approaches that are worth exploring are Custom Domain Name federation and Direct Federation, even if the latter is still in preview.

Custom Domain Name federation

This approach involves the creation of a Custom Domain Name inside your organization's Azure AD Directory. Once created and verified, you can proceed with setting up the federation between Azure AD and the external Identity Provider. This federation can rely on one of two different federation protocols: SAML 2.0 or WS-Federation.

In my previous blog post I've described how to set up a SAML-based federation between Azure AD and G Suite; if you are interested in the implementation details, please refer to it.

I would say this is a robust solution that allows identities, homed in an external Identity Provider, to authenticate themselves through Single Sign-On, without the necessity to create an Azure AD User or to redeem an invitation to your Azure Organization.

Direct Federation

Direct Federation is another approach that enables external users to collaborate in your Azure Organization in a B2B fashion. You can set up Direct Federation only if the IdP - that external users belong to - supports SAML 2.0 or WS-Federation protocol.

As for Custom Domain Name federation, you have to configure the federation both on the IdP and Azure side, as described (here).

On the Azure side, you have to complete the federation set up through Azure AD's External Identities console, as illustrated in the following picture.

Figure 2.

In this configuration, you still have to invite the external user, who has to redeem the invitation to collaborate in your Azure Organization.

Service Principal and Managed Service Identities

When it comes to talking about programmatic access, Service Principal and Managed Service Identities play a crucial role. Service Principal is tight to the concept of Application in the context of Azure.

Based on Azure's documentation, an Application is a template that defines "how the service can issue tokens in order to access the application, resources that the application might need to access, and the actions that the application can take". This template is used to instantiate one or more Service Principals, which are the concretization of the Application across different Tenants. When you create an Application, it comes with a default Service Principal, the "home" one.

A Service Principal defines what an Application can access inside a specific Tenant.

You can authenticate your automation script or software as a Service Principal through password-based or certification-based authentication. Password-based authentication requires you to provide the password that was specified during Service Principal creation. Certification-based authentication requires you to specify a certificate thumbprint that enables information retrieval from a local certificate store. Certificate-based authentication is considered a more secure solution but requires more effort to be maintained.

A natural evolution of Service Principals, when running software inside an Azure Tenant, is represented by Managed Service Identities.

Managed Identities avoid applications, that run on a specific virtual machine, to handle secrets. In particular, Managed Identities rely on the Azure Instance Metadata Service to retrieve temporary access tokens that are automatically rotated by Azure AD, without the need to write a logic responsible for that. Under the hood, a Managed Identity relies on a Service Principal, managed by Azure AD. A Service Principal is automatically created when we enable a Managed Identity for a virtual machine.

IMO, the way Azure Managed Identities work is pretty much similar to the way AWS's Instance Profiles generate temporary credentials through the AWS Instance Metadata Service.

The following picture gives a clear and complete overview of how Managed Identities mechanism works.

Figure 3.

Azure authorization: Role-Based Access Control

At this point, we've explored different Security Principals: Azure AD Users, Service Principals, and Managed Identities.

We didn't talk about User Groups, as it is a concept strictly related to RBAC. Azure AD helps you assign a set of access permissions to all the members of a group, instead of having to provide the rights one-by-one. Users inherit rights defined in the Group they belong to.

The Security Principal is one of the three actors involved in the Azure RBAC role assignment mechanism. The other two components involved are Role and Scope.

The Security Principal is the entity that, through role assignment, receives permissions to perform actions against resources in a specific Scope. Permissions are defined inside a Role.

The Scope

The Scope is basically a resource container, that allows specifying the group of resources the Security Principal has access to.

There are three types of Scopes or resources containers: Management Groups, Subscriptions, and Resource Groups.

As the name suggests, Resource Groups are groups of resources that belong to the same application, workload, or project. Resource Groups are used to manage related resources' lifecycle and settings in a homogeneous way.

Moving to a higher abstraction level, we find Subscriptions, which represents a way to organize and group resources that have the same billing model. You may have different Subscriptions under the same Azure Tenant.

A Subscription may be the leaf of a tree called Management Group. A Management Group is used by large organizations to manage and enforce policies - even RBAC ones - to Subscriptions. A Management Group may contain other Management Groups, creating a hierarchical structure up to six levels of depth.

The Role

While the Scope represents the group of resources a Security Principal can access, the Role specifies Security Principal's access rights.

A Role is a definition of the subset of actions a Security Principal can perform on a Resource Provider.

You may wonder what actually a Resource Provider is! Well, you can think of it as a resource supplier, which defines what management and data actions can be performed on its specific resources.

Figure 4.

The above picture illustrates two different kinds of Resources, Container and Blob, that are supplied by the same Resource Provider, i.e. Storage account. As you can see, there is a neat separation between Management and Data actions.

Management actions allow a Security Principal to manage access to Resources and their lifecycle. On the other hand, Data actions involve the access, manipulation, and deletion of data hosted in the Resources.

To give you a clear understanding of how Management and Data actions work, let me show you an example of role definition, i.e. the Storage Blob Data Reader built-in Role:

{
  "Name": "Storage Blob Data Reader",
  "Id": "2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
  "IsCustom": false,
  "Description": "Allows for read access to Azure Storage blob containers and data",
  "Actions": [
    "Microsoft.Storage/storageAccounts/blobServices/containers/read",
    "Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action"
  ],
  "NotActions": [],
  "DataActions": [
    "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/"
  ]
}

As specified in the description, this Role "Allows for read access to Azure Storage blob containers and data". In particular, Management actions - defined under "Actions" - allows a Security Principal to read and list Azure Storage containers; Data actions - defined under "DataActions" - allow to read and list Azure Storage blobs, that contain data.

When defining actions, you can use wildcard to cover a larger subset of operations the Role allows the Security Principal to perform on Resources.

NotActions and NotDataActions are arrays of strings that specify, respectively, the management and data operations that are excluded from the allowed Actions and DataActions.

In this case, both Management and Data actions can be applied to all scopes: management groups, subscriptions, or resource groups. This is possible only for built-in roles that make use of the root scope "/". When you define a custom role, you can make the role available for assignment in only the management groups, subscriptions, or resource groups that require it. You must use at least one management group, subscription, or resource group.

Last but not least, once you've defined the role, you can assign it to Security Principals at one of the AssignableScopes. For example, you can assign the Storage Blob Data Reader built-in Role to a Security Principal at a specific Resource Group's Scope, by creating a new role assignment from the Resource Group's IAM blade. That way, the Security Principal is allowed to perform actions based on the access rights defined in the Role definition, limited to the Resource Group's Scope.

The "DevOps point of view": different access scenarios

I focused the article on access strategies that are crucial from a DevOps point of view.

As I already said, access strategies have to be implemented based on the kind of task the person, or - using Azure terminology - the Security Principal, has to do.

Let's go back to the distinction between Operational and Development tasks.

Now that we have a better knowledge of different access strategies and approaches, it should be clear that Guest User invitation and Federation with external Identity Providers enables DevOps to perform tasks that fall into the Operational category. For what concerns Federation, there are plenty of different Identity Providers that you can federate with your Organization's Azure AD Directory, even on-premises ones. Please, refer to online guides - giving priority to the ones provided by Azure - to get more details about your IdP-specific federation setup.

As I said before, when it comes to enable programmatic access by your automation scripts and/or applications, Service Principals and Managed Identities are fundamental. We have already covered differences between these two actors, but let me make some considerations about the environment in which code is executed.

If I - as a developer - need to run my application or automation scripts locally, one of the possible ways to let them access Azure Resources is by using Service Principals. If I'm developing the application using the Azure SDK, the Service Principal should be created with the following command.

az ad sp create-for-rbac --sdk-auth

The newly created Service Principal information follows a standard JSON format, which contains a ClientId and a ClientSecret, among other properties. You can use this JSON to authenticate with token credentials or perform file-based authentication.

That said, this is not the best practice for production applications to retrieve temporary credentials. The de facto standard in that sense is represented by Managed Identities that, as I explained before, rely on the Azure Instance Metadata Service to generate and auto-rotate short-term credentials associated with a managed Service Principal.

The following Python code snippet gives you an idea of how it is simple to instantiate Managed Identity credentials using Azure SDK.

from msrestazure.azure_active_directory import MSIAuthentication

credentials = MSIAuthentication()

That's all, folks!

I hope you find this blog post interesting and useful. We covered many different Azure AD authentication and authorization aspects, tailored to a DevOps point of view. I've shared some of my knowledge with you. Now it's your turn! I'll really appreciate your feedback and, most of all, real-world examples that allow me to improve the article's quality.

New AWS EC2 Mac Instances: a CI/CD test bench

Eric Villa — Fri, 08 Jan 2021 12:26:45 +0000

During the last AWS re:Invent, AWS made one of the most discussed announcement, that — on paper — opens a lot of new scenarios: AWS EC2 Mac Instances!

Don't worry, we will deepen one of these scenarios later on in this blog post, but let's first introduce this new instance type.

Amazon EC2 Mac Instances come with an 80s name, which makes them more attractive to those of you who are a little bit older than me 🙂. They're called mac1.metal instances.

Talking about hardware, Amazon EC2 Mac Instances are backed by Mac mini hosts, that rely on AWS Nitro controllers to connect with AWS network infrastructure and services. The interesting point is that Mac Instances are connected to the Nitro System through the Thunderbolt 3 interface. I used the term "host" to highlight the fact that we're not dealing with Virtual Machines, but with Dedicated Hosts; whenever I decide to run an Amazon EC2 Mac Instance, AWS provisions a concrete Mac mini host for my purposes.

Peter Desantis, Senior Vice President of AWS Infrastructure and Support, presenting new Amazon EC2 Mac Instances at AWS re:Invent 2020 Infrastructure Keynote.

mac1.metal — the specs

At this point — assuming that you never heard about Amazon EC2 Mac Instances hardware specifications — you may wonder what are the supported sizes. Well, as far as now, you can forget the word "choice": AWS allows you to run only one size of Mac Instances. mac1.metal instances' hardware specifications tell us that they're powered by an Intel Coffee Lake processor running at 3.2 GHz — that can burst up to 4.6 GHz — and 32 GiB of memory. As explained by Jeff Barr in the AWS News Blog, instances run in a VPC, include ENA networking, and are natively Optimized for communication with EBS volumes, supporting I/O intensive workloads.

In my daily routine, my working partner is a macOS laptop that I had to update to the new macOS Big Sur operating system. So far it didn't bring me tangible enhancements, but it's quite a best-practice to keep your system up to date, at least on your workstation. AWS EC2 Mac Instances come with a limitation in that sense: only Mojave or Catalina macOS versions can be selected. Mojave and Catalina AMIs comes with the AWS CLI, Command Line Tools for Xcode, Homebrew, and SSM Agent already installed. AWS is working to add support for Big Sur, and for Apple M1 Chip.

A practical Use Case

Now, let's focus on what I like the most: practical use cases!

I started my career as a developer, and I guess every developer's mind made — at least — an association between this announcement and the possibility to automate building, testing, and signing of macOS and iOS applications.

During the last year, my team has been developing an Open-Source Desktop Application that manages local credentials to access complex Cloud Environments. Our application is written in TypeScript, interpreted by Node.js. We used Angular as our development framework, which runs on top of an Electron engine for cross-platform compatibility.

Electron comes with a native application builder, called electron-builder, that we used to write custom build scripts in our package.json file, which contains dependencies specifications too. We wrote custom scripts to build Linux, Windows, and macOS binaries.

In order to build the macOS binary, the script needs to have access to the Signing Certificate and to the Apple Notarisation Password. They allow, respectively, to sign and notarize the macOS binary. We usually store these secrets in our macOS Keychain, run the build scripts on our local environments, and manually upload the artifacts on our GitHub repository as a new release. This is a common practice adopted by many developers when building macOS or iOS applications.

This process is slow, cumbersome, and may lead to human errors. But hey, there seems to be a new opportunity out there for us. What better Use Case for the new Amazon EC2 Mac Instances than building our application's macOS binary?

It's time to focus on how I set up the test bench. We will go through the following steps:

launch of a blend new mac1.metal instance;
access to the instance;
installation of packages and tools needed during the build process;
configuration of the build pipeline with the dear old Jenkins.

Launch a mac1.metal instance

The first thing we've to do to get our pipeline set up consists of the creation of the Amazon EC2 Mac Instance on which we're going to install and configure Jenkins.

Let's jump into the AWS console!

As for any other EC2 instance, the launch wizard of a mac1.metal kicks off from EC2 console, in the "Instances" section. As many of you already know, here you can find the list of EC2 instances available and — among the others — the menu needed to launch a new instance.

Since the 30 November 2020, the AMI list is richer: indeed, it shows both Mojave and Catalina AMIs; for our purposes, I choose Catalina.

When it comes to choosing the instance type, there is only one available, called mac1.metal. As we already know, it is characterized by 12 vCPUs running at 3.2GHz and 32GiB of memory. If you think of it as your workstation it does not sound that weird!

In the rest of the wizard, we can treat our Mac Instance like any other instance type; the only thing that we should take particular attention to is the tenancy. We're going to launch the instance on a Dedicated Host that we can request — on a separate tab — during the instance creation process. Even for the Dedicated Host, we've to specify mac1.metal as the type of instances that can be launched on it.

For the sake of this proof of concept, I decided to run the instance in a public subnet, and enable Public IP auto-assignment.

To allow the installation of the heavy-weight Xcode — which provides some critical build tools — attach an EBS root volume with an appropriate size to the instance; in my case, I choose to attach a 100GiB-sized EBS volume.

What about access types?

Before diving into Mac Instance access types, remember to setup Security Group rules that allow you to reach it through SSH and VNC. Moreover, I configured a rule to allow access through my browser to port 8080 of the instance, i.e. the one associated with the Jenkins service. Since I decided to run the instance in a public subnet, I restricted access to the instance only to my IP address.

DISCLAIMER: it works, but please note that the setup I used — in terms of networking — cannot be considered production-ready! To make it more secure, it is enough to move the Mac Instance inside a private subnet, and place an OpenVPN server in the public subnet; that way, the mac1.metal instance is no more exposed directly to the internet and we can access it by the means of the OpenVPN server.

In the last step of the instance creation wizard, we've to choose whether to select an existing .pem key or to create a new one to access the instance via SSH. That's the first access type available, and it's no different from SSH access to an Amazon Linux instance; indeed, the username for Mac Instances is ec2-user.

If you need a graphical access to the instance — which will be needed while installing packages and tools — you can use VNC; if you're a macOS user, you can rely on VNC Viewer software to setup the connection to your mac1.metal instance.

But wait — as AWS Technical Evangelist Sébastien Stormacq explains in this video — there is something you've to configure on the instance before having the possibility to access it. In particular, you've to set a password for the ec2-user, and enable the VNC server. Here is the GitHub Gist I've followed, and that is very precious to me:

NOTE: 45-49 lines are critical in the sense that, without them, you'll not be able to install Xcode; the initial APFS container size is not large enough to accommodate Xcode.

And that's all for what concerns access types.

Let's install some packages and tools

The build pipeline that we are going to configure comes with some prerequisites that we've to satisfy. So, what are these prerequisites?

A Java installation
Xcode Application, because default Command Line Tools do not provide altool, which is needed to notarise the app.
The actual Jenkins service

Where possible, I relied on brew to install packages. In particular, I've used it to install Java and Jenkins; then, I've installed Xcode from the App Store, providing my Apple Credentials.

Install Xcode first, the process is straightforward: open the App Store, search for Xcode, and install it.

Now, let's focus on Java. I choose Java AdoptOpenJDK 11 version, which can be installed using brew in this way:

# Update brew first of all
brew update

# Add adoptopenjdk/openjdk repository
brew tap adoptopenjdk/openjdk

# Install Java AdoptOpenJDK 11
brew install --cask adoptopenjdk11

To install Jenkins, I've used the following command:

brew install jenkins-lts

Once installed, we've to make Jenkins accessible from outside by modifying the /usr/local/opt/jenkins-lts/homebrew.mxcl.jenkins-lts.plist file. In particular, we've to change the --httpListenAddress option from 127.0.0.1 to 0.0.0.0. Then, simply start the service using the following command:

brew services start jenkins-lts

Jenkins initial configuration

Jenkins's initial configuration involves three steps:

unlock Jenkins — in this step, we've to retrieve the password that was written inside the /Users/ec2-user/.jenkins/secrets/initialAdminPassword file;
install plugins — in addition to the pre-selected ones, check NodeJS, Git Parameter, and GitHub plugins;
create admin user — finally, create the admin user, providing credentials, full name, and email address.

Credentials & Secrets

Before focusing on the build job, let's create all the credentials and secrets needed to pull the code from the repo, sign the binary, notarize it, and finally push the artifacts back to the GitHub repo as a new release draft.

So, what are the credentials and secrets needed by the build job?

GitHub personal access token
Apple signing certificate (in base64 format)
Apple notarisation password

I set them as global secrets from /credentials/store/system/. Here, add credentials and secrets respecting these types:

The GitHub personal access token 2 secret is different from the first one, in the sense that it is used to push the artifacts back to the GitHub repo, while the first one is used to pull the code from the repo.

Build Job configuration

We can start the Build Job configuration wizard by clicking "New Item" from the sidebar on the left of the Dashboard. For what concerns this wizard, we'll go into the details of Source Code Management, Build Triggers, Build Environment Bindings, and Build sections.

In the Source Code Management section, we've to specify the coordinates of our GitHub repository, providing access credentials, repo URL, and the branch from which Jenkins will pull the code from.

I've decided to make Jenkins check for newly available commits every 5 minutes, in a polling fashion; the alternative consists of setting up a Jenkins webhook invoked directly by GitHub, in a push fashion.

Next step: Environment Variables, which I referred to as Build Environment Bindings. Here we have simply to assign the previously configured credentials and secrets to environment variables used in the Build Job's steps.

And finally, let's add the build steps! I divided the build in five steps, i.e. five Execute shell commands, which I want to illustrate down here.

# Step 1
chmod +x ./scripts/add-osx-cert.sh

# Step 2
./scripts/add-osx-cert.sh

# Step 3
npm install

# Step 4
npm run rebuild-keytar

# Step 5
npm run dist-mac-prod

Apart from step 3 and step 4, you may wonder what add-osx-cert.sh and dist-mac-prod scripts consist of. Therefore, I want to provide you their implementation.

project-root-folder/scripts/add-osx-cert.sh

#!/usr/bin/env sh

KEY_CHAIN=build.keychain
CERTIFICATE_P12=certificate.p12

echo "Recreate the certificate from the secure environment variable"
echo $CERTIFICATE_OSX_P12 | base64 --decode > $CERTIFICATE_P12

echo "security create-keychain"
security create-keychain -p jenkins $KEY_CHAIN
echo "security list-keychains"
security list-keychains -s login.keychain build.keychain
echo "security default-keychain"
security default-keychain -s $KEY_CHAIN
echo "security unlock-keychain"
security unlock-keychain -p jenkins $KEY_CHAIN
echo "security import"
security import $CERTIFICATE_P12 -k $KEY_CHAIN -P "" -T /usr/bin/codesign;
echo "security find-identity"
security find-identity -v
echo "security set-key-partition-list"
security set-key-partition-list -S apple-tool:,apple:,codesign:, -s -k jenkins $KEY_CHAIN

# Remove certs
rm -fr *.p12

dist-mac-prod — custom script which has to be added in the script section of the package.json file

"dist-mac-prod": "rm -rf electron/dist && rm -rf release && rm -rf dist && tsc --p electron && ng build --aot --configuration production --base-href ./ && mkdir -p electron/dist/electron/assets/images && cp -a electron/assets/images/* electron/dist/electron/assets/images/ && electron-builder build --publish=onTag",

For the sake of this article, the important part of the dist-mac-prod script is

electron-builder build --publish=onTag

which triggers the build of the binary.

Inside the package.json file, there is another important part that we've to specify, and that is included in the "build" section; let's show that down here.

# ...
"build": {
        "publish": [
            {
                "provider": "github",
                "owner": "ericvilla",
                "repo": "leapp",
                "releaseType": "draft"
            }
        ],
        "afterSign": "scripts/notarize.js",
# ...

As you can see, I'm requesting to push the artifact to the ericvilla/leapp repo — which is a fork of https://github.com/Noovolari/leapp — as a new DRAFT release.

Moreover, I specified to run the script/notarize.js script after signing. This script is responsible for macOS application notarisation, and is implemented as follows:

const { notarize } = require('electron-notarize');

exports.default = async function notarizing(context) {
  const { electronPlatformName, appOutDir } = context;
  if (electronPlatformName !== 'darwin') {
    return;
  }

  const appName = context.packager.appInfo.productFilename;

  return await notarize({
    appBundleId: 'com.noovolari.leapp',
    appPath: `${appOutDir}/${appName}.app`,
    appleId: "mobile@besharp.it",
    appleIdPassword: process.env.APPLE_NOTARISATION_PASSWORD ? process.env.APPLE_NOTARISATION_PASSWORD :
      "@keychain:Leapp",
  });
};

It relies on electron-notarize package and looks for APPLE_NOTARISATION_PASSWORD environment variable; if it is not available, it assumes you're running the build in your local environment. Therefore, it looks for appleIdPassword inside the System's Keychain.

Last but not least, I had to install a Node.js version from inside Jenkins in order to build the solution correctly. To do that, move to the "Manage Jenkins" section, accessible from the left sidebar. Once inside it, click "Global Tool Configuration"; there you can install the Node.js version you need. In my case, I've installed Node.js 12.9.1 version.

Here we are, at the end of the Build Job configuration!

If Jenkins service is running and the Build Job is set up, it checks for new pushes on the GitHub repo, and triggers the build process.

If everything worked fine, you'll be able to find the newly created Release Draft under https://github.com///releases path.

Let's Sum Up

And now, it's time to make some considerations!

When reading this blog post everything seems to be clear and straightforward (well, I hope that to be so 🙂), but during my first set up I got in trouble many times, and I want to highlight that here.

First of all, do you know that in order to run a Mac Instance you've to allocate a Dedicated Host for at least 24 hours? Maybe yes. But, in the context of this use case, it is critical to have the possibility to run build jobs only when needed; you may argue "ok, but you set up Jenkins to check for new commits in a polling fashion", and I would say you're right. Indeed, we usually rely on container-based services like AWS CodeBuild to run build environments, let's say, on-demand. It may be more convenient to run the build manually in your local environment, or automatically by setting up Jenkins as we did, but on your local machine.

Why I'm saying that?

Simple. A Mac Instance Dedicated Host is not cheap: it costs $1.083 per hour, which means almost $26 fixed costs whenever I decide to run a new one (Dedicated Host allocated for at least 24 hours). Due to the Dedicated Host minimum allocation time limitation, IMO it is not possible — at least very difficult — to set up cost savings strategies, like running the CI/CD instance only during working hours, e.g. 8 hours per day.

That's not all.

If you decide to run a Mac Instance, you've to take into account the fact that sometimes EC2 instance Health Checks do not pass; that means — for EBS-backed AMIs — that you need to stop the instance, wait until the Dedicated Host exits the pending status, and finally restart the instance. What does it mean? A lot of wasted time.

I'm using what may sound like a polemic tone, but constructively. I think that's a great announcement, and that this service has a lot of potentials. Yes, potential, because I felt it is a little bit immature yet.

Apart from these considerations, the process of setting up a pipeline with Jenkins is exactly the same as in my local environment, and the different ways we have to access the Mac Instance grants us a complete experience.

That's all folks!

Here we are.

My thanks go to every member of my team, in particular to Alessandro Gaggia, who helped me getting out of troubles, and who gave me moral and technical support during Jenkins setup.

I hope you find this blog post useful, and that lots of questions and ideas raised in your minds. In that case, please do not hesitate to contact me; it will be a pleasure to share considerations about this or other use-cases.

Stay tuned for new articles!

How to SAML federate your Azure account with G Suite

Eric Villa — Wed, 28 Oct 2020 14:21:54 +0000

Why should I use an external Identity Provider?

One of the most seen patterns in talking about Cloud Access Management consists of adopting an external Identity Provider to store, manage, and authenticate your corporate identities that need to access resources in multiple Cloud Providers.

Enabling Access to those resources involves setting up a federation between your Cloud Accounts and your Identity Provider.

In the previous blog post, we described how to set up a federation between G Suite, as the Identity Provider, and AWS, as the Service Provider. Here we will shift the focus on the federation process between G Suite and Azure.

If you come from the Azure world, you have probably used - or at least seen - Azure AD as your Identity Provider to access resources contained in your Azure accounts; it is relatively straightforward.

But what if you are new to Azure and want to make it accessible by your G Suite users without migrating them to Azure AD or another Identity Provider?

Read on, you're in the right place!

We are showing you the path to a convenient and maintainable solution for delegating corporate identity management and authentication to an already set up Identity Provider.

Use case: Access Azure accounts through the Azure CLI

Let's assume a real-world use case:

Figure 1: Federated Single Sign-On that involves G Suite ad IdP and Azure as SP.

This scenario shows a G Suite user - or identity - logging into Azure through the Azure CLI's az login command.

As you can see, to allow G Suite identities to access Azure, it is necessary to Federate the G Suite Organisational Unit with the Azure AD Domain; we will see later in this article how to implement it.

Keep in mind that Azure AD remains Azure's entry point even if it doesn't act as Identity Provider. Azure AD delegates the authentication process to G Suite.

Role-Based Access Control for Azure resources

Once a user has authenticated against the Identity Provider, he can access resources in different Azure Subscriptions based on his assigned roles. This kind of Access is called Role-Based Access Control or RBAC.

To better understand how RBAC works, we start presenting the main actors involved.

The first one we will focus on is the Tenant. It represents "the organization that owns and manages a specific instance of Microsoft Cloud Services," i.e. a specific Tenant manages one or many Microsoft Cloud Services subscriptions, from Microsoft Office 365 to Microsoft Azure.

Each Tenant is associated with one and only one Directory, which represents the Azure AD service.

In its default configuration, the Azure AD Directory is responsible for managing and authenticating a user pool. As stated before, in this configuration, the Identity Provider is an external one, i.e. G Suite.

We can associate a directory to one or many Subscriptions; users' Role-Based Access to these Subscriptions is controlled through Azure Identity and Access Management (IAM) service.

We can control Role-Based Access at four different levels:

Management Groups - help you manage your Azure subscriptions by grouping them;
Subscriptions - help you organize access to Azure resources and determine how resource usage is reported, billed, and paid for;
Resource Groups - containers that hold related resources for an Azure solution;
Resources - Cloud Resources, e.g., Virtual Machines, Databases.

Figure 2: Different levels of scope at which RBAC can be configured.

This system allows you to define granular access to your resources by your corporate users.

Federation Tutorial

Now that you know how RBAC works and the idea behind the federation between an Azure AD Custom Domain and an external IdP, let's focus on the Federation Tutorial steps.

1) G Suite SAML Application setup

The first step of this tutorial is about creating a Custom SAML Application inside the G Suite Admin Console. This application represents your Service Provider, i.e. Microsoft Azure, in the G Suite side.

The Custom SAML Application contains all the information needed to send a digitally signed XML document containing the identity provider's authenticated identity to the Service Provider.

This XML document is called SAML Assertion and will be signed by the Identity Provider using an X.509 Certificate shared with the Service Provider.

The Service Provider uses the shared Certificate to retrieve and validate the SAML Assertion.

Once logged into the Admin Console, navigate to Apps from the Dashboard. From the Apps menu, select SAML apps. The SAML apps section provides you a list of the existing SAML Applications and allows you to create a new one by clicking the plus yellow button on the page's bottom right.

A new 5-steps wizard will be opened;

in the wizard's first step, select SETUP MY OWN CUSTOM APP.

Go on and choose Option 2 to download the IdP information in the form of IdP metadata. IdP metadata is an XML file that contains the X.509 Certificate, too; that's why I suggest you store it in a secure place. Moreover, it will be used in the last step of this tutorial to configure Azure AD Custom Domain's authentication method as federated.

At this point, you need to configure the Custom SAML Application's name, description, and logo; the last two properties are optional.

In the wizard's fourth step, provide the following SSO details to configure your Custom SAML Application:

ACS URL

Description: The Service Provider's URL to which the SAML Assertion will be forwarded once the user has authenticated himself successfully.

Value: https://login.microsoftonline.com/login.srf
Entity ID

Description: indicates the audience the SAML Assertion is intended.

Value: urn:federation:MicrosoftOnline
Name ID

Description: SAML assertion attribute indicating who the user is.

Value: Basic Information > Primary email
Name ID Format

Description: defines Name ID's format.

Value: PERSISTENT

Figure 3: SAML Application's Service Provider Details definition.

The last step consists of the attribute mapping definition, which is used to determine a mapping between attributes defined inside the SAML Assertion and attributes used inside the Service Provider. In this case, it is not necessary to define them, while it is fundamental if you want to federate a G Suite Organisational Unit with an AWS Account, but this is not the case.

Once created, you should be able to see the SAML Application in the SAML apps section.

2) Azure AD Custom Domain Name setup

In this step, we will configure a new Azure AD Custom Domain Name; you can skip it if you've already created one that suits your needs.

Move to Azure Active Directory service in the Azure management console, and select Custom domain names in the left sidebar to open the relative section.

If you've never created a custom domain before, you should see only one domain, i.e. the default primary domain which name ends with .onmicrosoft.com. If this is your case, please leave it as your primary domain.

Now click on + Add custom domain to create a new custom domain. A right sidebar will appear; here, you have to specify the new custom domain's name.

Figure 4: Add custom domain.

Once the custom domain name is specified, you can move to the domain verification step by clicking the Add domain button.

Figure 5: Custom domain verification.

As illustrated in Figure 5, you need to verify the newly created custom domain name by creating a TXT record with your domain name registrar using the provided information. As your custom domain has been verified, its Status attribute should appear as Verified.

DON'T set the new custom domain as the primary one; otherwise, you will not be able to federate it to the external Identity Provider.

3) Users import

To enable corporate users to access your Azure Subscriptions, you have to add them to your Azure Active Directory before federating the custom domain to G Suite.

You can do that from Azure Active Directory's Users section, which is reachable by clicking Users in the left sidebar.

You can add new users to your Azure Active Directory in the Users section by clicking + New user. You can even upload a CSV file containing your corporate users by clicking Bulk operations > Bulk create.

Figure 6: Azure Active Directory users creation.

Before proceeding with the federation setup, remember to set users' ImmutableId. You may wonder what ImmutableId is? Well, it is an attribute that uniquely identifies a user in Azure Active Directory's context. To make federated Access work fine, ImmutableId should correspond to the user's email address.

You can configure Users' ImmutableId using the Set-MsolUser command from the PowerShell's MSOnline module.

To install the MSOnline module through PowerShell, use the following command:

Install-Module MSOnline

Once installed, you can connect to your Azure Tenant through Connect-MsolService and set the user's ImmutableId through Set-MsolUser. Connect-MsolService requires you to authenticate with your Azure credentials.

Be sure you are authenticating as a Member User and have sufficient privileges to run the Connect-MsolService command.

Connect-MsolService
Set-MsolUser -UserPrincipalName <user-email> -ImmutableId <user-email>

If your necessity is to import many users to Azure AD, it would be easier to set their ImmutableId automatically. e.g., using a PowerShell script that iterates over the list of imported users and runs the Set-MsolUser command for each of them.

At this point, imported Azure AD users, which belong to the newly created Custom Domain, can still not sign in using G Suite credentials since the Custom Domain has not yet been federated to the G Suite Organisational Unit.

To make a practical example, you will be able to access Azure resources using the az login command, but you can't do that providing your G Suite User credentials.

So, let's move to the step that could appear innocent at first glance, but I guarantee a real pain when it's the first time you're dealing with it, causing you to struggle to find the right documentation setup to make it work fine.

4) Federation setup through PowerShell script

Here we will see how to federate your Azure AD Custom Domain with your G Suite Organisational Unit using a PowerShell script cause it seems the only way to do that, at least in my experience.

Here is the PowerShell script we used to set up the federation:

Install-Module MSOnline

Connect-MsolService

$domainName = "<your-custom-domain-name>"
[xml]$idp = Get-Content <metadata-xml-file-path>
$activeLogonUri = "https://login.microsoftonline.com/login.srf"
$signingCertificate = ($idp.EntityDescriptor.IDPSSODescriptor.KeyDescriptor.KeyInfo.X509Data.X509Certificate | Out-String).Trim()
$issuerUri = $idp.EntityDescriptor.entityID
$logOffUri = $idp.EntityDescriptor.IDPSSODescriptor.SingleSignOnService.Location[0]
$passiveLogOnUri = $idp.EntityDescriptor.IDPSSODescriptor.SingleSignOnService.Location[0]

Set-MsolDomainAuthentication `
  -DomainName $domainName `
  -FederationBrandName $domainName `
  -Authentication Federated `
  -PassiveLogOnUri $passiveLogOnUri `
  -ActiveLogOnUri $activeLogonUri `
  -SigningCertificate $signingCertificate `
  -IssuerUri $issuerUri `
  -LogOffUri $logOffUri `
  -PreferredAuthenticationProtocol "SAMLP"

This script invokes three cmdlets:

Install-Module, to install the MSOnline module, which contains the other cmdlets necessary to set up the federation between Azure AD and G Suite;
Connect-MsolService, already described before, and used to connect to your Azure Tenant;
Set-MsolDomainAuthentication, to set up the Custom Domain's authentication method to federated.

I suggest looking at the documentation page for a complete description of the Set-MsolDomainAuthentication cmdlet and its parameters.

Let's focus on three parameters, except the DomainName one, which corresponds to the Azure AD's Custom Domain Name you should already have set up.

Authentication - These parameters make Azure AD manage authentication autonomously or delegate authentication to an external IdP, in this case, G Suite. To complete Azure AD delegate authentication, we set Authentication to Federated.
SigningCertificate - The value associated with this parameter corresponds to the X.509 certificate included in the metadata XML file downloaded during the G Suite SAML Application creation phase. It is necessary for the Service Provider, i.e. Azure AD, as the gateway to Azure Subscriptions, to retrieve the signed authentication response. As you can see from the script, the metadata XML file is loaded from the local path in which you placed it.
PreferredAuthenticationProtocol - It is crucial to specify SAMLP as the protocol used to authenticate users against the Identity Provider, as we set up a SAML Application on the G Suite.

Keep your fingers crossed and run the script... Hopefully, a check in the Federated column should appear!

Finally, you've successfully federated your Azure AD Custom Domain with your G Suite Organisational Unit.

Now, log in! 🚀

At this point, we have all the instruments set up to log into your Azure Tenant with your G Suite credentials; it's needless to say that, to test the federated single sign-on, you should have a G Suite User's credentials in your hands. The same User should be present in the Azure Active Directory, as explained before.

Now let's demonstrate the flow described in Figure 1, gaining Azure access tokens through Leapp, our Open Source credentials management tool.

I've already federated my test G Suite Organisational Unit with my test Azure Tenant, which contains a Subscription accessible by my User as Reader. The reader is the role of my User, on the Azure side, for the Subscription I want to access. This role assignment follows RBAC rules.

Inside Leapp, to add a new Azure Subscription, click the + square button on the top-right side of the accounts list, which is empty as you run Leapp for the first time.

Figure 7a: Add an Azure Subscription using Leapp.

Then, click on the Azure icon to open the Azure Subscription creation form.

Figure 7b: Add an Azure Subscription using Leapp.

You've to provide the alias and the ID of your Azure Subscription; moreover, you've to supply the ID of the Tenant that contains the Subscription.

Once saved, you should see the new Azure Subscription in the accounts list.

Figure 8: Newly created Azure Subscription shows up in the accounts list.

By clicking the card associated with the Subscription, Leapp will initiate the federated single sign-on flow, assuming that you've set up federation correctly.

What do I mean with the federated single sign-on flow? I mean prompting for a G Suite User's credentials since Azure AD delegates the authentication to G Suite.

Under the hood, Leapp invokes the az login command, opens a new tab in your default browser, and redirects you to the G Suite login page. If we provided the right credentials, we'd be authenticated and issue Azure CLI's commands from the terminal. In this case, as we've associated a Reader role to the Azure AD User, we can issue the az vm list command to retrieve the list of VMs in the Subscription. The Azure CLI relies on the temporary credentials generated by Leapp and stored in the ~/.azure/accessTokens.json file.

Final considerations

In this article we learned how to set up a federation between G Suite and Azure and the reason that drives the adoption of this access pattern.

We applied this access pattern to a real use case in which we gained access to an Azure Subscription quickly and easily using Leapp.

We control User's privileges inside our Azure Tenant through the Role-Based Access Control concept, which we will deepen in one of the next publications.

For what concerns security, RBAC plays a key role in this scenario. In addition to assign proper roles to specific Users inside our Tenant, it may be necessary to add MFA on the IdP side, i.e. G Suite, to protect our Cloud Environment following best-practices.

That's all, folks!

I hope you enjoyed this blog post, and that it gave a clear understanding of how SAML federated access to Azure from G Suite can be set up and controlled, from a security point of view.

Of course, this is only one of the possible configurations enabling access to Azure; have you ever find yourself to deal with this, or similar use cases? Are there any other related aspects you'd like to explore?

Give us your feedback! It is always welcome and appreciated, and allows us to provide better content, aligned to real world applications.