# Certificate attribute mapping


 IAM Roles Anywhere provides you with the capability to define a custom set of mapping rules, enabling you to specify which data are extracted from authenticating certificates as session tags for authorization policies. These customized attribute mappings are associated with a [profile](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rolesanywhere-profile.html). 

 Attributes are data elements that come from specific fields in the certificate. You can use specifiers to represent one or more attributes. 

**Note**  
 For information about session tag quotas, see [Session tagging operations](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_operations). 

**Topics**
+ [

## Default mapping behavior
](#attribute-mapping-default)
+ [

# Put attribute mappings
](put-attribute-mapping.md)
+ [

# Delete attribute mappings
](delete-attribute-mappings.md)
+ [

# Attribute mapping and trust policy
](attribute-mapping-and-trust-policy.md)

## Default mapping behavior


The following attributes are mapped by default when you create a profile. The default mapping rules are as follows: 
+ `x509Subject`: maps all supported Relative Distinguished Names (RDNs) from an authenticating certificate's Subject into distinct `PrincipalTag` elements in the session.
+ `x509Issuer`: maps all supported Relative Distinguished Names (RDNs) from an authenticating certificate's Issuer into distinct `PrincipalTag` elements in the session.
+ `x509SAN (Subject Alternative Name)`: maps the ** first** value of the following types: `DNS Names`, `Directory Name (DN)`, and `URI Names`

 To view your current mappings associated with a profile, using the following command: 

```
$ aws rolesanywhere get-profile --profile-id PROFILE_ID
```

 Default mapping rules in a JSON format: 

```
"attributeMappings": [
  {
    "mappingRules": [
        {
            "specifier": "*"
        }
    ],
    "certificateField": "x509Issuer"
  },
  {
    "mappingRules": [
        {
            "specifier": "DNS"
        },
        {
            "specifier": "URI"
        },
        {
            "specifier": "Name/*"
        }
    ],
    "certificateField": "x509SAN"
  },
  {
    "mappingRules": [
        {
            "specifier": "*"
        }
    ],
    "certificateField": "x509Subject"
  }
]
```

**Note**  
If you see `*` as a specifier, it signifies the default behavior, which maps all recognizable RDNs for `x509Subject`, `x509Issuer` and `x509SAN/Name`. However, `*` does not have a defined behavior in the context of `x509SAN/URI`, `x509SAN/DNS`, or `x509SAN/`. The specifier `Name/` represents the first recognizable attribute of the `Directory Name`. Both `Name` and `Name/` are equivalent to `Name/*` and will be displayed as `Name/*`in the mapping rule.

# Put attribute mappings


## Put attribute mappings (command line interface)


 `put-attribute-mapping` enables you to attach new mapping rules to your profile. When using that profile, the certificate mapping behavior changes according to your customized rules. 

 To put a mapping rule, using the following command: 

```
$aws rolesanywhere put-attribute-mapping \
        --certificate-field CERTIFICATE_FIELD \
        --mapping-rules specifier=SPECIFIER \
        --profile-id PROFILE_ID
```

 The `CERTIFICATE_FIELD` can be in one of `x509Subject`, `x509Issuer` and `x509SAN`. The `SPECIFIER` is a string enforced by a standard (for example, OID) that can map to a piece of information encoded in the certificate. 

For example, to add mapping rules for `x509Subject/CN` and `x509Subject/OU`, use the following command:

```
$aws rolesanywhere put-attribute-mapping \
        --certificate-field x509Subject \
        --mapping-rules specifier=CN specifier=OU \
        --profile-id PROFILE_ID
```

## Put attribute mappings (console)


1. Sign in to [IAM Roles Anywhere console](https://console.aws.amazon.com/rolesanywhere/home).

1. Scroll to find profile table and **choose the profile** to add certificate attribute mappings.

1. Within profile detail page scroll towards **Certificate attribute mappings** section and choose **Manage mappings**.

1. Scroll to find the **Add mappings** button and click on it.

1. Choose a certificate field from either `Subject`, `Issuer`, or `Subject Alternative Name` in the dropdown list, and enter the specifier

1. Select **Save changes** to add attribute mappings.

# Delete attribute mappings


## Delete attribute mappings (command line interface)


 `delete-attribute-mapping` enables you to delete mapping rules from your profile. When using that profile, the attribute specified by the deleted mapping rule will not be mapped from a certificate. 

 To delete a mapping rule, using the following command: 

```
$aws rolesanywhere delete-attribute-mapping \
        --certificate-field CERTIFICATE_FIELD \
        --specifiers SPECIFIERS \
        --profile-id PROFILE_ID
```

 The `CERTIFICATE_FIELD` can be in one of `x509Subject`, `x509Issuer` and `x509SAN`. The `SPECIFIER` is a string enforced by a standard (for example, OID) that exists in your current mapping rules. 

For example, to delete mapping rules for `x509Subject/CN` and `x509Subject/OU`, use the following command:

```
$aws rolesanywhere delete-attribute-mapping \
        --certificate-field x509Subject \
        --specifiers CN OU \
        --profile-id PROFILE_ID
```

## Delete attribute mappings (console)


1. Sign in to [IAM Roles Anywhere console](https://console.aws.amazon.com/rolesanywhere/home).

1. Scroll to find profile table and **choose the profile** to remove certificate attribute mappings.

1. Within profile detail page scroll towards **Certificate attribute mappings** section and choose **Manage mappings**.

1. Scroll to find the corresponding attribute mapping row and click on **Remove mapping** button associated with it.

1. Select **Save changes** to remove attribute mappings.

# Attribute mapping and trust policy


 It is recommended to have condition statements in the Assume Role Policy Document to restrict authorization based on attributes that are extracted from an end-entity X.509 certificate. For more information about the role trust policy, see [Trust policy](trust-model.md#trust-policy). 

 The attribute mapping field of a profile controls which attributes from an authenticating X.509 certificate will be mapped for principal tags. Therefore, while adding condition statements to an Assume Role Policy Document, be cautious that the specifiers used in mapping rules for authorization need to be mapped accordingly. 

The following example shows trust policies that add a condition based on the `Issuer Common Name (CN)` of the certificate.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "rolesanywhere.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession",
        "sts:SetSourceIdentity"
      ],
      "Condition": {
        "StringEquals": {
          "aws:PrincipalTag/x509Issuer/CN": "Bob"
        },
        "ArnEquals": {
          "aws:SourceArn": [
            "arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/TA_ID"
          ]
        }
      }
    }
  ]
}
```

------

If a profile is used with an Attribute Mapping field that lacks `specifier: CN` or `specifier: *` in the mappingRules for `x509Issuer`, the first condition in the Assume Role Policy Document will evaluate as `false` because there will be no value mapped `aws:PrincipalTag/x509Issuer/CN`.

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "rolesanywhere.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession",
        "sts:SetSourceIdentity"
      ],
      "Condition": {
        "StringNotEquals": {
          "aws:PrincipalTag/x509Issuer/CN": "Bob"
        },
        "ArnEquals": {
          "aws:SourceArn": [
            "arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/TA_ID"
          ]
        }
      }
    }
  ]
}
```

------

Likewise, if the condition is `StringNotEquals`, the condition will evaluate to `true` using the same profile. This happens because the condition is disregarded when the principal tag is dropped due to attribute mapping APIs.

Having the Attribute Mapping field provided below in a profile, the `StringEquals` condition for `x509Issuer/CN` will assess to `false`, or the `StringNotEquals` condition will assess to `true`.

```
"attributeMappings": [
  {
    "mappingRules": [
        {
            "specifier": "O"
        }
    ],
    "certificateField": "x509Issuer"
  },
  {
    "mappingRules": [
        {
            "specifier": "DNS"
        },
        {
            "specifier": "URI"
        },
        {
            "specifier": "Name/*"
        }
    ],
    "certificateField": "x509SAN"
  },
  {
    "mappingRules": [
        {
            "specifier": "*"
        }
    ],
    "certificateField": "x509Subject"
  }
]
```