| copyright | lastupdated | keywords | subcollection | ||
|---|---|---|---|---|---|
|
2023-01-25 |
trusted profile, dynamic rule, operators, rules, conditions, properties |
account |
{{site.data.keyword.attribute-definition-list}}
{: #iam-condition-properties}
Dynamic rules and trusted profiles both use conditional IAM statements that you specify to automatically add federated users to access groups or trusted profiles. When users log in with a federated ID, the data from the identity provider (IdP) dynamically maps them to an access group based on conditions that you set. For more information, see Creating dynamic rules for access groups and Creating trusted profiles.
You can also assign conditional IAM access policies to designate temporary access to resources in your account or allow access to resources during specific time windows. For more information, see Limiting access with time-based conditions and review the section Conditions in /v2/policies access policies.
{: #general-details}
Each dynamic rule and trusted profile trust relationship has the following properties:
Name : Enter a custom name that helps you remember what type of users you are adding to an access group or trusted profile.
Identity provider (IdP)
: The dynamic rule or trusted profile is evaluated only if the user who is logging in authenticates by using the enterprise IdP with this issuer URI. Your IdP URL is displayed in the console for you to copy and paste when you create a dynamic rule or trusted profile. For example, https://w3id.sso.ibm.com/auth/sps/samlidp2/saml20. You can also view th IdP by clicking View identity provider (IdP) data. For IBMid, the IdP is the SAML "entityId" field, sometimes referred to as the issuer ID, and is part of the federation configuration when you are onboarding with IBMid. For AppID, equivalent syntax is the "realm ID". For more information, see Enabling authentication from an external identity provider
Session duration : The dynamic access group membership or trusted profile session expires after the number of hours that are specified in this property. For example, if the property is set to 24 hours, the user’s dynamic or trusted profile session ends one day (24 hours) after they log in.
{: #condition-properties}
Additionally, each dynamic rule and trusted profile trust relationship has one or more conditions that consist of the following properties. Users need to satisfy all conditions for the overall dynamic rule or trusted profile authentication to evaluate to true:
Allow users when : An attribute name that is part your identity provider data. To learn more about how attribute names are created from your enterprise identity provider to the condition evaluation, see Mapping of enterprise identity provider attributes{: external}.
Comparator
: Compares the attribute that is specified in the Allow users when field with the Values property. You can choose from Equals, Not Equals, Equals Ignore Case, Not Equals Ignore Case, In, and Contains. Use the Contains option when the attribute statement has an array type. You can enter more than one value to be matched by using the In option.
Values
: An attribute value that is used by the comparator to evaluate against the Allow users when attribute name.
You can think of a dynamic rule or trusted profile condition as a key:value pair. The key is what you add in the Allow users when field, and the value is what you enter in the Values field.
{: tip}
{: #comparators}
| Comparator | Description | Sample condition |
|---|---|---|
| Equals | Case-sensitive string comparison. Boolean or number values are converted into a string before comparison. | primaryGroup Equals “Admins” |
| Not Equals | Negated case-sensitive string comparison. Boolean or number values are converted into a string before comparison. | primaryGroup NotEquals “Admins” |
| Equals Ignore Case | Case-insensitive string comparison. Boolean or number values are converted into a string before comparison. | isManager EqualsIgnoreCase “tRuE” |
| Not Equals Ignore Case | Negated case-insensitive string comparison. Boolean or number values are converted into a string before comparison. | is_teamlead NotEqualsIgnoreCase “TrUe” |
| Contains | If the attribute is an array of strings, numbers, or Booleans, Contains determines by using the comparator Equals if the value that is provided is part of the array in the login message. If the attribute is a single string instead, Contains determines whether the value that is provided is contained in the string attribute in the login message. |
group contains “Admins” |
| In | Short notation for multiple Equal operators. Compares the value in the login message attribute with the list of potential values in this rule. Boolean or numbers are converted to a string before comparison. | jobRole in [“Manager”,”Director”,”Team-Lead”] |
| {: caption="Table 1. Available comparators for conditions" caption-side="top"} |
{: #example-values}
The following table includes values for each of the fields for a dynamic rule or a trusted profile condition. In this example, users who are identified as managers within the federated IdP are mapped to an {{site.data.keyword.Bluemix_notm}} access group or trusted profile that has specific access set for only managers.
| Field | Value |
|---|---|
| Name | Manager |
| Identity provider | https://idp.example.org/SAML2 |
| Session duration in hours | 12 |
| Allow users when (attribute name) | isManager |
| Comparator | Equals |
| Value | true |
| {: caption="Table 2. Example values" caption-side="top"} |
{: #cr-attribute-names}
To establish trust with a compute resource in a trusted profile, you can use the {{site.data.keyword.cloud_notm}} console, {{site.data.keyword.cloud_notm}} CLI, or the IAM API. If you select All service resources and add conditions to filter the compute resource instances that can apply the profile, the conditions are built based on the following resource attributes.
{: #cr-kub-rhos}
| {{site.data.keyword.cloud_notm}} console name | CLI and API name | Description |
|---|---|---|
| Resource group ID | resource_group_id |
The ID of the resource group that contains this cluster. You can identify the resource group of a cluster by using its overview page in the IBM Cloud Console. |
| Resource group name | resource_group_name |
The name of the resource group that contains this cluster. |
| Service instance | service_instance |
The ID of this cluster. You can retrieve this value from the cluster's overview page in the IBM Cloud Console as "Cluster ID" or using the IBM Cloud CLI. |
| Location | location |
Location of the cluster derived from its cloud resource name. |
| Namespace | namespace |
Namespace of the service account that is used to retrieve a Compute Resource token and get an IAM token. |
| Service account | name |
Name of the service account that is used to retrieve a Compute Resource token and get an IAM token. |
| Pod | pod |
The name of the Kubernetes pod that runs the code that wants to retrieve an IAM token. |
| {: caption="Table 3. Kubernetes and Red Hat OpenShift attribute names" caption-side="top"} |
{: #cr-vpc}
| {{site.data.keyword.cloud_notm}} console name | CLI and API name | Description |
|---|---|---|
| Resource group ID | resource_group_id |
The ID of the resource group that contains this cluster. You can identify the resource group of a cluster by using its overview page in the IBM Cloud Console. |
| Resource group name | resource_group_name |
The name of the resource group that contains this cluster. |
| Resource ID | resource |
The ID of the virtual server for VPC. |
| Instance group name | instance_group_name |
Name of the instance group, if this virtual server is part of one. |
| Region | region |
Region into which this virtual server is deployed. |
| Subnet | subnet_id |
The subnet ID of the virtual server for VPC, if one is available. |
| VPC ID | vpc_id |
The VPC ID of the virtual server for VPC, if one is available. |
| Zone | zone |
Zone name in which this virtual server is deployed to. |
| {: caption="Table 4. Virtual server for VPC attribute names" caption-side="top"} |
{: #cr-rule-cli-examples}
The following examples show how you can use the attribute names in the CLI to build trusted profile links and conditions.
{: #tp-link-cluster}
To link the trusted profile Test to the Kubernetes cluster c0pigdctkkc07fs7pm06 in the account 444aebb0657c7f0f3aae8e7bdc78709a and service account my-service-account in the namespace my-namespace, specify the following command:
ibmcloud iam trusted-profile-link-create Test --name NewLink4IKS --cr-type IKS_SA \
--link-crn
crn:v1:bluemix:public:containers-kubernetes:us-east:a/444aebb0657c7f0f3aae8e7bdc78709a:c0pigdctkkc07fs7pm06:: \
--link-namespace "my-namespace" \
--link-name "my-service-account"{: pre}
{: #tp-condition-cluster}
To connect the trusted profile with the ID Profile-b2f13064-2b8c-4e4b-9181-c1973a408e3c to all service accounts in the Kubernetes cluster c0pigdctkkc07fs7pm06 in the account 444aebb0657c7f0f3aae8e7bdc78709a and the service account namespace my-namespace, specify the following command:
ibmcloud iam trusted-profile-rule-create Profile-b2f13064-2b8c-4e4b-9181-c1973a408e3c \
--name NewRule4IKS --type Profile-CR --cr-type IKS_SA \
--conditions "claim:service_instance,operator:EQUALS,vlaue:c0pigdctkkc07fs7pm06" \
--conditions "claim:namespace,operator:EQUALS,value:my-namespace"{: pre}
{: #tp-condition-vpc}
To connect the trusted profile with the ID Profile-b2f13064-2b8c-4e4b-9181-c1973a408e3c to all virtual servers in one VPC r206-1db73eed-b0fb-b04f-bb57-4d3a3c2dff9d in the account 444aebb0657c7f0f3aae8e7bdc78709a, specify the following command:
ibmcloud iam trusted-profile-rule-create Profile-b2f13064-2b8c-4e4b-9181-c1973a408e3c \
--name NewRule4VSI --type Profile-CR --cr-type VSI \
--conditions "claim:vpc_id,operator:EQUALS,value:r206-1db73eed-b0fb-b04f-bb57-4d3a3c2dff9d"{: pre}
{: #policy-condition-properties}
Time-based conditions for IAM access policies use /v2/policies syntax. Policies that use /v1/policies syntax aren't eligible to add time-based conditions. For more information, see Access policy version limitations.
To view the new schema for policies, see /v2/policies.
{: #time-based-conditions}
The following table lists the operators available for creating time-based conditions for access policies.
| Operator | Description | Example |
|---|---|---|
dayOfWeekAnyOf |
The days of the week that the client can use the policy. \n 1 - Monday \n 2 - Tuesday \n 3 - Wednesday \n 4- Thursday \n 5 - Friday \n 6 - Saturday \n 7 - Sunday | See example. |
timeGreaterThanOrEquals |
The time that the condition begins granting access. Time is calculated by <time>±<time_zone_offset>. |
See example. |
timeLessThanOrEquals |
The time that the condition terminates access. Time is calculated by <time>±<time_zone_offset>. |
See example. |
dateTimeGreaterThanOrEquals |
The date and time that the condition begins granting access. Date is calculated by <datetime>±<time_zone_offset>. |
See example. |
dateTimeLessThanOrEquals |
The date and time that the condition terminates access. Date is calculated by <datetime>±<time_zone_offset>. |
See example. |
| {: caption="Table 6. The operators available to time-based conditions for access policies." caption-side="top"} |
When you define a condition with a GreaterThanOrEquals operator, always include a condition with a LessThanOrEquals operator. This way, there is a clearly defined duration, whether it is temporary, recurring all day, or recurring with custom hours. For more information, see Condition patterns.
For date and time operators, policies support the ISO 8601 format hh:mm:ss±hh:mm. The time zone offset refers to Coordinated Universal Time.
{: note}
Use the following variables to represent the key that specifies the client’s environment attribute, which the policy evaluates against. Each key supports a discrete set of operators.
| Variable name | Description | Supported operations |
|---|---|---|
environment.attributes.current_time |
The client's current time. | timeGreaterThanOrEquals, timeLessThanOrEquals |
environment.attributes.current_date_time |
The client's current date and time. | dateTimeGreaterThanOrEquals, dateTimeLessThanOrEquals |
environment.attributes.day_of_week |
The client's current day of the week. | dayOfWeekAnyOf, dayOfWeekEquals |
| {: caption="Table 7. Variable notation for time-based conditions." caption-side="top"} |
{: #dayOfWeekAnyOf-timeGreaterThanOrEquals-timeLessThanOrEquals}
The days of the week that are specified in this example map to Monday, Tuesday, Wednesday, and Thursday. The timeGreaterThanOrEquals value indicates that the condition begins granting access at 9 AM in the time zone UTC-5. The timeLessThanOrEquals value indicates that the condition terminates access at 5 PM in the time zone UTC-5.environment.attributes.current_time and environment.attributes.day_of_week indicate that it is a recurring time-based condition. Always include time conditions with a dayOfWeek condition.
"conditions": [
{
"key": "{{environment.attributes.day_of_week}}",
"operator": "dayOfWeekAnyOf",
"value": [
1,
2,
3,
4
]
},
{
"key": "{{environment.attributes.current_time}}",
"operator": "timeGreaterThanOrEquals",
"value": "09:00:00-05:00"
},
{
"key": "{{environment.attributes.current_time}}",
"operator": "timeLessThanOrEquals",
"value": "17:00:00-05:00"
}
]{: codeblock}
{: #dayOfWeekEquals}
The day of the week in this example is represented by 3 in the value string, which maps to Wednesday. In that same string, +6:00 represents the time zone UTC+6:00. There's only one condition, so it's nested under "rule".
"rule": {
"key": "{{environment.attributes.day_of_week}}",
"operator": "dayOfWeekEquals",
"value": "3+06:00"
},{: codeblock}
{: #dateTimeGreaterThanOrEquals-dateTimeLessThanOrEquals}
In this example, the dateTimeGreaterThanOrEquals value indicates that the condition begins granting access on 26 December 2022 at 9 AM in the UTC-5 time zone. The dateTimeLessThanOrEquals value indicates that the condition terminates access on 27 December 2022 at 5 PM in the UTC-5 time zone. environment.attributes.current_date_time indicates that it is a temporary time-based condition.
"conditions": [
{
"key": "{{environment.attributes.current_date_time}}",
"operator": "dateTimeGreaterThanOrEquals",
"value": "2022-12-26T09:00:00-05:00"
},
{
"key": "{{environment.attributes.current_date_time}}",
"operator": "dateTimeLessThanOrEquals",
"value": "2022-12-27T17:00:00-05:00"
}
]{: codeblock}