Skip to main content

Working with OAuth 2.0 or SAML IdP groups in ONTAP

Contributors netapp-bhouser
PDFs

ONTAP provides several options for configuring groups based on your OAuth 2.0 authorization server or SAML identity provider (IdP). The groups can then be mapped to roles which are used by ONTAP to determine access.

Beginning with ONTAP 9.17.1, SAML IdP-provided group information can be mapped to ONTAP roles. This allows you to assign roles to users based on the groups that are defined in the IdP. For more information, see Configure SAML authentication. Beginning with ONTAP 9.14.1, ONTAP supports group name authentication for OAuth 2.0. Beginning with ONTAP 9.16.1, ONTAP supports OAuth 2.0 group UUID authentication and role mapping. For more information, see Overview of the ONTAP OAuth 2.0 implementation.

How groups are identified

When you configure a group at an authorization server or SAML IdP, it's identified and carried in an OAuth 2.0 access token or SAML assertion using either a name or UUID. You need to be aware of how your authorization server or SAML IdP handles groups before configuring ONTAP.

Note If multiple groups are included in an access token, ONTAP will attempt to use each one until there is a match.

Group names

Many authorization servers and SAML IdPs, like Active Directory Federation Service (ADFS), identify and represent groups using a name. Here's a fragment of a JSON OAuth 2.0 access token generated by ADFS containing several groups. See Manage groups with names for more information.

  ...
  "sub": "User1_TestDev@NICAD5.COM",
  "group": [
    "NICAD5\\Domain Users",
    "NICAD5\\Development Group",
    "NICAD5\\Production Group"
  ],
  "apptype": "Confidential",
  "appid": "3bff3b2b-8e40-44ba-7c11-d73c3b76e3e8",
  ...

Group UUIDs

Some authorization servers and SAML IdPs, like Microsoft Entra ID, identify and represent groups using a UUID. Here's a fragment of an OAuth 2.0 access token generated by Entra ID containing several groups. See Manage groups with UUIDs for more information.

  ...
  "appid": "4aff4b4b-8e40-44ba-7c11-d73c3b76e3d7",
  "appidacr": "1",
  "groups": [
    "8ea4c5b0-bcad-4e66-8f1e-cd395474a448",
    "a8558fc2-a1b2-4cb7-cc41-59bd831840cc"],
  "name": "admin007 with group membership",
  ...

Manage groups with names

If your authorization server or SAML IdP uses names to identify groups, you need to make sure each group is defined for your ONTAP cluster. Depending on your security environment, you might already have the group defined.

Here's an example CLI command defining an ONTAP group. Notice it uses a named group from the sample access token. You need to be at the ONTAP admin privilege level to issue the command.

Example
security login create -user-or-group-name "NICAD5\\Domain Users" -application http -authentication-method domain -role admin

Use -authentication-method domain or nsswitch for SAML IdP and OAuth 2.0 authorization server groups.

Note You can also configure this feature using the ONTAP REST API. Learn more in the ONTAP automation documentation.

Manage groups with UUIDs

If your authorization server or SAML IdP represents groups using UUID values, you need to perform a two-step configuration before using a group. Beginning with ONTAP 9.16.1, two mapping features are available and have been tested with Entra ID. Entra ID for OAuth 2.0 is supported beginning with ONTAP 9.16.1, and Entra ID for SAML is supported beginning with ONTAP 9.17.1. You need to be at the ONTAP admin privilege level to issue the CLI commands.

Note You can also configure these features using the ONTAP REST API. Learn more in the ONTAP automation documentation.

Map a group UUID to a group name

If you're using an authorization server or SAML IdP that represents groups using UUID values, you need to map the group UUIDs to group names. The primary ONTAP CLI operations are described below.

Create

You can define a new group mapping configuration with the security login group create command. The group UUID and name should match the configuration at the authorization server or SAML IdP. Learn more about security login group create in the ONTAP command reference.

Parameters

The parameters used to create a group mapping are described below.

Parameter Description

vserver

Optionally specifies the name of the SVM (vserver) the group is associated with. If omitted, the group is associated with the ONTAP cluster.

name

The unique name of the group that ONTAP will use.

type

This value indicates the identity provider the group originates from.

uuid

Specifies the universally unique identifier of the group as provided by the authorization server or SAML IdP.

Here's an example CLI command defining a group for ONTAP. Notice it uses a UUID group from the sample access token.

Example
security login group create -vserver ontap-cls-1 -name IAM_Dev -type entra -uuid 8ea4c5b0-bcad-4e66-8f1e-cd395474a448

After creating the group, a unique read-only integer identifier is generated for the group.

Additional CLI operations

The command supports several additional operations, including:

  • Show

  • Modify

  • Delete

You can use the show option to retrieve the unique group ID generated for a group. Learn more about show in the ONTAP command reference.

Map a group UUID to a role

If you're using an authorization server or SAML IdP that represents groups using UUID values, you can map the group to a role. For more information on Role-Based Access Control in ONTAP, refer to Learn about managing ONTAP access-control roles. The primary ONTAP CLI operations are described below. You need to be at the ONTAP admin privilege level to issue the commands.

Note You need to first map a group UUID to a group name and retrieve the unique integer ID generated for the group. You'll need the ID to map the group to a role.

Create

You can define a new role mapping with the security login group role-mapping create command. Learn more about security login group role-mapping create in the ONTAP command reference.

Parameters

The parameters used to map a group to a role are described below.

Parameter Description

group-id

Specifies the unique ID generated for the group using the command security login group create.

role

The name of the ONTAP role the group is mapped to.
Example
security login group role-mapping create -group-id 1 -role admin

Additional CLI operations

The command supports several additional operations, including:

  • Show

  • Modify

  • Delete

Learn more about the commands described in this procedure in the ONTAP command reference.

Related information