Introduction

This tutorial guides you through the setup of groups in a public cloud to control access to resources for a set of people. It takes advantage of attributes that your enterprise identity provider sends during your login time. This way, dynamic assignment of access to resources can be implemented, which can dramatically ease the administration of your public cloud account. This task is usually executed by administrators and operators of public cloud accounts.

To demonstrate the necessary steps, this tutorial uses the Identity and Access Management (IAM) component of IBM Cloud. Upon completion of this tutorial, you will be able to:

  • Create groups to manage access.
  • Add people and technical user IDs (service IDs) to groups.
  • Assign access policies to all members of a group.
  • Define dynamic rules for groups.
  • Understand how attributes from your enterprise identity provider are propagated to public clouds.
  • Understand how users are added to groups based on dynamic rules that leverages those attributes.

Prerequisites

To follow the steps in this tutorial, you require the following:

  • IBMid

    If you do not already have an IBMid, you can create one when you sign up for a free IBM Cloud account below.

  • IBM Cloud account membership

    Create a free IBM Cloud account or ask a friend or colleague who already owns an IBM Cloud account to invite you. A portion of this tutorial covers the creation of dynamic rules for an access group, which can only be done with a federated ID set up by your company’s enterprise identity provider. However, you can execute the other parts of this tutorial without a federated ID.

  • Authorization to create and edit access groups in IBM Cloud

    If you are the owner of the IBM Cloud account you are using for this tutorial, then you already have all necessary authorization to create and edit access groups. Otherwise, ask the owner of the account to follow these instructions to give you authorization.

Estimated time

You should be able to complete this tutorial within 45 minutes.

Steps

As with most public clouds, the IBM Cloud public environment allows you to create a group of identities to effectively manage access to resources (within IBM Cloud, this is called an access group). Then, you can assign a policy to the group, which is faster than assigning the same policy multiple times per user.

Step 1: Create an access group

  1. Log in to IBM Cloud to launch your IBM Cloud Dashboard.

  2. Since you can be a member of multiple accounts in IBM Cloud, make sure that you start within the correct account in which you intend to create the access group.

    Select the correct account

  3. From the Manage menu, select Access (IAM).

    Navigate to "Access (IAM)"

  4. On the Manage access and users page, select Access groups. You can now see a list of existing access groups and a Create button. If this button is missing, make sure that you have selected the correct account and you are authorized to create and edit access groups in that account, as described in the Prerequisites section of this tutorial.

    Access IAM User Interface

  5. Click Create to open the “Create access group” dialog box.

  6. In the Name field, type Cloudant Admins
  7. In the Description field, type Users that can administer Cloudant instances in this account.
  8. Click Create to close the dialog box and see the details of your new access group.

    Access group details

For more details about this page, refer to Setting up access groups.

Step 2 (Optional): Add static members to your access group

If required, you can now add people to your access group that should always be members of that group. In IBM Cloud, they are called static members.

  1. In your access group details pane (titled Manage Cloudant Admins by the actions you took in Step 1), click Add users.
  2. Select the people that you want to be added as static members. If you cannot see the person that you want to add, you may need to invite them to join your account.

    Select a user to be added

  3. Click Add to group.

    Access group with one static member

Step 3 (Optional): Add service IDs to your access group

If required, you can also add service IDs to your access groups. In IBM Cloud, service IDs are technical user IDs that are used for application-to-service and service-to-service invocations. By using service IDs for xxx-to-service interactions, you can make your application independent from the existence of a specific user.

  1. At the top of your access group details pane (titled Manage Cloudant Admins by the actions you took in Step 1), select the Service IDs tab.
  2. Click Add service ID.
  3. Select the service IDs from the list that you want to add as static members.

    Select a service ID to be added

  4. Click Add to group.

For more information about creating service IDs, refer to Creating and working with service IDs.

Step 4: Add access policies

With an access group, you can assign a single policy to the group instead of assigning the same policy multiple times per individual user or service ID. For this tutorial, we will assign an IBM Cloudant database administrator role to the members of our access group without any further restrictions.

  1. At the top of your access group details pane (titled Manage Cloudant Admins by the actions you took in Step 1), select the Access policies tab.
  2. Click Assign access.
  3. Click Assign access to resources.
  4. From the list of Services, select Cloudant. Additional lists will appear, but leave them as-is for the purposes of this tutorial.
  5. Under Assign platform access roles, select the Administrator check box.

    Select role "Administrator"

  6. Click Assign in the lower right of the window.

    Access group with access policy


Background information about access groups and dynamic rules

The final two steps of this tutorial are focused on creating dynamic rules for an access group. But first, let’s discuss the relationship between dynamic rules, access groups, and conditions.

Dynamic rules and their evaluation

In IBM Cloud, access groups can contain dynamic rules. These rules allow IBM Cloud to proactively add users to access groups. To decide if a user should be added to an access group, IBM Cloud requires attributes of the user that logs in. As shown later in the Mapping of enterprise identity provider attributes section of this tutorial, these attributes are available when the user logs in via the enterprise identity provider’s user interface.

Other cloud providers may have slightly different dynamic rules available, but the basic concept stays the same: dynamic rules have to evaluate conditions based on attributes that are provided by the enterprise identity provider. The result of this evaluation will influence a user’s access to resources at the log in moment.

Each dynamic rule has the following properties:

  • Name

    Choose a name for your rule so that you can remember later what this rule is meant for.

  • Identity provider

    The dynamic rule will only be evaluated if the user who is logging in authenticates via the enterprise identity provider with this issuer URI.

  • Expiration

    The dynamic membership expires after the number of hours that are specified in this property. For example, if the property is set to 24, the user’s dynamic membership will be revoked one day (24 hours) after he logged in.

Additionally, each dynamic rule has one or more conditions consisting of the following properties and all properties need to apply to let the overall dynamic rule evaluate to true:

  • Add users when

    References an attribute name that is part of the login message sent from your identity provider to IBM Cloud. The Mapping of enterprise identity provider attributes section of this tutorial explains how these attribute names are propagated from your enterprise identity provider to the condition evaluation.

  • Comparator

    One of the comparators listed in Table 1 compares the attribute referenced in the Add users when property with the values provided in the Values property.

  • Values

    Provide a value that should be used by the comparator to evaluate this rule.

Table 1: Available comparators for conditions

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 Determines using the comparator Equals if the value that is provided is part of the attribute in the login message. Can only be applied on attributes containing arrays of strings, numbers, or Booleans. groups 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. Again, Boolean or numbers are converted to a string before comparison. jobRole in [“Manager”,”Director”,”Team-Lead”]

See Figure 1 for an explanation of how dynamic rules are defined and evaluated in IBM Cloud. Other cloud providers work in a similar way.

Figure 1. Relationship between access group, dynamic rule, and condition

Relationship between access group, dynamic rule, and condition

An access group can have zero to multiple dynamic rules. Only the dynamic rules that have the correct identity provider configured will be evaluated. A dynamic rule evaluates to true, only if all conditions will evaluate to true. This means, all conditions within a dynamic group are connected using a logical AND operator.

If one or more dynamic rules apply (for example, evaluate to true), the person that logs in is added to the access group as a dynamic user with the expiration specified in the dynamic rule. This means, the dynamic rules are combined with a logical OR operator. If more than one dynamic rule apply, then the longest expiration will be applied.

Mapping of enterprise identity provider attributes

If your company has federated with IBMid, your enterprise identity provider can send arbitrary attributes together with your login message (security assertion). Any other attributes provided by the organization in the security assertion will be sent through to the end IBM Cloud service being used by the user, but will not be persisted in the IBMid system in any way.

See the following sample of an assertion using the Security Assertion Markup Language (SAML) to understand how attributes are provided and processed so that you can leverage them later when setting up dynamic rules.

<samlp:Response ...>
  <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
    https://w3id.sso.ibm.com/auth/sps/samlidp2/saml20
  </saml:Issuer>
  <ds:Signature .../>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:success"/>
  </samlp:Status>
  <saml:Assertion Version="2.0" IssueInstant="2019-07-01T08:35:37Z" .../>
    <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
      https://w3id.sso.ibm.com/auth/sps/samlidp2/saml20
    </saml:Issuer>
    <ds:Signature .../>
    <saml:Subject>
      <saml:NameID Format="urn:ibm:names:ITFIM:5.1:accessmanager">
        Martin.Smolny@de.ibm.com
      </saml:NameID>
      ...
    </saml:Subject>
    ...
    <saml:AttributeStatement>
      <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                      Name="firstName">
        <saml:AttributeValue xsi:type="xs:string">Martin</saml:AttributeValue>
      </saml:Attribute>
      ... (more attributes like uid, lastName, company, cn)
      <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
                      Name="blueGroups">
        <saml:AttributeValue xsi:type="xs:string">Group 1</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">Group 2</saml:AttributeValue>
        ... (more groups)
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

In the case of IBM Cloud, the IBMid now:

  • Receives this SAML assertion.
  • Validates that the issuer URI https://w3id.sso.ibm.com/auth/sps/samlidp2/saml20 is registered.
  • Validates the incoming SAML assertion against the already uploaded manifest data, including signature validation and potential decryption of the payload.
  • Creates an IBMid token containing information about the user who is logging in, augmenting that ID token with the additional SAML assertion attributes.

Based on the above SAML assertion sample, the corresponding IBMid token will have the following format:

{
  "iss": "https://idaas.iam.ibm.com",
  "ext": "{\"blueGroups\":[\"Group 1\",\"Group 2\"],
           \"tenantId\":\"idaas.iam.ibm.com\",\"company\":\"IBM\"}",
  "sub": "Martin.Smolny@de.ibm.com",
  [...]
  "given_name": "Martin",
  "family_name": "Smolny",
  "realmName": "https://w3id.sso.ibm.com/auth/sps/samlidp2/saml20",
  "uniqueSecurityName": "2*********X",
  "exp": 1562234338,
  "iat": 1562230738
}

From this information inside the IBMid token, IBM Cloud is providing the following attributes to be used for dynamic rules:

  • firstName is propagated as IBMid token claim given_name. For dynamic rules, the attribute name firstName can be used to access this attribute.
  • lastName is propagated as IBMid token claim family_name. For dynamic rules, the attribute name lastName can be used to access this attribute.
  • realmName provides the SAML assertion issuer.

All additional SAML assertion attributes that are propagated via the ext claim in the IBMid token are added. For the case above, this is blueGroups, which is a list of groups in which the user is member of. The following two attributes are also made available through the ext claim in the IBMid token:

  • tenantId is currently always idaas.iam.ibm.com.
  • company corresponds to the SAML assertion attribute company.

Steps continued

Now that you have deeper insight into dynamic rules conditions, comparators, and their usage in IBM Cloud, you can create dynamic rules to test the functionality.

Step 5: Create a dynamic rule for the access group

Your goal in this tutorial is to dynamically assign a policy for users that log in to IBM Cloud. To achieve that, you need to create a dynamic rule that leverages attributes provided by your enterprise identity provider:

  1. At the top of your access group details pane (titled Manage Cloudant Admins by the actions you took in Step 1), select the Dynamic rules tab.

    Add dynamic rules to access groups

  2. Click Add rule.

  3. The data that loads within the Identity provider data section shows you the attributes available for the users in the group. Check for any warnings and error messages, such as “pop-up messages are suppressed”. If a pop-up warning message asks you to log in, follow the steps to do so.
  4. In the Name field, type a short description of the dynamic rule.
  5. In the Identity provider field, specify the issuer URI of your enterprise identity provider, which is the realmName attribute located in the Identity provider data section.
  6. In the Expiration field, type or select 24 to let the dynamic membership expire after 24 hours.

    Dynamic rule with condition

Next, you have to define one or more conditions that all need to apply to let the overall rule evaluate to true (for simplicity, choose just one condition for this tutorial):

  1. In the Add users when field, type an attribute that appears within the Identity provider data section that is available for the users in the group. As you can see in the sample data above, blueGroups is an attribute that loaded for me.
  2. Select a Comparator from the list. See Table 1 for descriptions of the available comparators.
  3. In the Values field, type a value that should be used by the comparator to evaluate your rule. As you can see in the sample data above, Group 1 is a valid value for me.
  4. Click Add rule to add your new rule to the dynamic rule list.

    Access group with dynamic rule

You can enter multiple dynamic rules for an access group and if all conditions for one of those rules evaluate to true, then the user is added to the access group dynamically. If you need further attributes from your enterprise identity provider available in your dynamic rules, contact your provider’s support team. They will be able to add arbitrary attributes to the SAML assertion, such as work team memberships or other user properties.

Step 6: Validate that the dynamic rule is applied

To validate that your dynamic rule applied correctly, you need a second user ID in your IBM Cloud account that currently does not have access to Cloudant, but can pass the conditions you established by the dynamic rule created in Step 5.

  1. Return to your IBM Cloud Dashboard.
  2. Click Create Resource, which is located in the upper-right corner of the window.
  3. Search the catalog for Cloudant and click the resulting box to open.

    Cloudant database service

  4. In the Service name field, type TestDynamicRules-Cloudant to distinguish this instance from previously existing Cloudant databases.

  5. From the Available authentication methods list, Use only IAM.
  6. Click Create.

    Cloudant configuration

  7. To validate that your new Cloudant instance is visible and provisioned correctly, check that TestDynamicRules-Cloudant appears in the Resource List. (You may need to expand the Services category to see it.)

    Cloudant instance in the resource list

  8. Click TestDynamicRules-Cloudant to open the service dashboard.

  9. Log out of IBM Cloud. (Some enterprise identity providers make it hard to log out while a browser session is still up and running. Therefore, I recommend that you close all browser instances to completely finish any existing sessions.)
  10. Restart you browser and log in to IBM Cloud with your second user ID to validate that the dynamic rule is evaluated correctly.
  11. In the Resource List, verify that your current user ID can see the TestDynamicRules-Cloudant instance, even though there is no policy for this user ID.

If your second user ID can see the new Cloudant instance, it means the ID was dynamically added to the Cloudant Admins access group and therefore received authorization to manage Cloudant databases. You successfully validated the dynamic rule!

Additional Comments

Due to the SAML assertions technology, updates to the group membership based on dynamic rules will only happen when a user ID logs in via the IBM Cloud console user interface. When you list the users inside your access group, only static members will show up. Nevertheless, for authorization decisions, dynamic users are considered correctly. There are several options to test if a user ID was correctly added to an IBM Cloud access group as dynamic user:

  • IBM Cloud CLI

    If your access group defines additional policies that influence commands that you can execute on the IBM Cloud CLI, first log in via the IBM Cloud console, and then try out one of these actions in the command line interface to see if the new policy applies. Your dynamic group membership will be valid on the console for API calls and also for CLI commands.

  • IBM Cloud Kubernetes Service

    The IBM Cloud Kubernetes Service is configured to use IBM Cloud IAM roles and leverages access groups to assign Kubernetes specific permissions. You may want to give your access group additional permissions on a cluster. Test if these additional permissions are available after logging in using your enterprise identity provider.

Keep in mind that group membership based on dynamic rules will expire as indicated in the rule. This means, you will lose some of your policies after the expiration time.

Summary

In this tutorial, you:

  • Created an access group.
  • Added static members to that access group.
  • Added access policies to the access group so that the membership will have an impact on authorization decisions.
  • Learned about dynamic rules and how they evaluate, which conditions and comparators exist, and how attributes from your enterprise identity providers are propagated into dynamic rules evaluation.
  • Added a dynamic rule to an access group.
  • Validated that the dynamic rule was executed correctly.

Dynamic rules will make managing the authorization for public cloud services easier for you.