Configure an external Open Authorization 2.0 authorization server

Configure OAuth 2 external authorization servers to give external applications access to Splunk data without the need for Splunk credentials.

You can configure an external Open Authorization version 2.0 (OAuth 2) server to let external applications connect to and access data that is stored on the Splunk platform without having to share credentials from the Splunk platform. This configuration lets you connect your external identity provider (IdP) to the Splunk platform by defining an OpenID Connect (OIDC) server for the client application on the IdP to interface with the Splunk platform for the purpose of authorization. Since the IdP provides the credentials, you do not need to use Splunk credentials to provide access to the Splunk data.

How the Splunk platform uses OAuth 2.0 to provide access to its data from external applications

The Splunk platform has its own default authentication configuration, known as native authentication. When you configure a Splunk platform instance with native authentication, users can log into the instance and, depending on the user and the roles that the user holds, they have access to the data that you, as the Splunk administrator, provide to them through those roles.

A growing number of use cases prevent use of this basic form of authentication. OAuth 2.0 lets administrators share access to resources without having to provide local credentials to external consumers of those resources. This lets all authorization happen on the IdP, from the client application that you define on the IdP.

In the case of the Splunk platform, configuring OAuth 2.0 support consists of several steps:

  1. Resource owners first configure and register a client application on their external IdP which the IdP uses to connect to the Splunk platform with a designated client ID and secret.

  2. They then provide an OIDC server on the Splunk platform through an OAuth 2.0 configuration.

  3. After that, they map groups on the IdP to roles on the Splunk platform instance that hosts the OIDC server.

After you set up the OIDC server on the Splunk platform instance:

  1. The client application authenticates against the IdP using its client credentials and receives a token from the IdP.

  2. The IdP connects to the Splunk OIDC server through the client application and exchanges its token for a Splunk token.

  3. Further REST API calls from the client application use the Splunk token for authentication, accessing Splunk data that is available to them through the group-to-role mappings that you made when you set up the OIDC. The client application on the IdP never uses Splunk credentials to access the Splunk platform instance.

Define an OAuth 2.0 external application server

Defining an external application server on your Splunk Enterprise instance lets you allow incoming connections from client applications on your identity provider (IdP) to access Splunk data.

To let external Open Authorization version 2.0 client applications access your Splunk platform instance for the purposes of accessing Splunk data, you must have the following items in place:

  • An OAuth 2.0 client application that is registered on your identity provider (IdP) with necessary client credentials including the client ID and client secret

  • The issuer URL, client ID claim, and Java Web Key Sets (JWKS) URL from the IdP client application. The IdP administrator provides this information. If you are the IdP administrator, then you must set up and retrieve this information from the IdP.

  • Administrator access to your Splunk platform instance. Specifically, the Splunk user you log in with must hold at least one role that contains the 'list_oauth_configs" and "edit_oauth_configs" Splunk capabilities.

  1. Log into your Splunk platform instance.
  2. Select Settings > Authentication Methods.
  3. Under External Frameworks, select Open Authorization (OAuth) 2.0. The OAuth 2.0 page loads.
  4. Select + New Configuration. The New Configuration page loads.
  5. In the Configuration Name field, enter a name for the configuration that you will remember.
  6. In the Issuer URL field, enter the URL that identifies the OAuth 2.0 server in the tokens that the OAuth 2.0 server creates.
  7. In the JSON Web Key Set URL field, enter the URL from the IdP client application that represents the set of JavaScript Object Notation (JSON) Web Key Set (JWKs) that are used to verify JSON Web Tokens that the authorization server issues.
  8. In the Audience field, specify the expected audience for this configuration. Typically, the audience will be "splunk" for the purposes of an external OAuth client application connecting to your Splunk platform instance, but can be any string that is pertinent to your organization's needs.
  9. In the Client ID claim field, enter the name of the JSON Web Token (JWT) claim that contains the client ID. This claim comes from the client application that you set up on the IdP. The Splunk platform uses this ID to identify the client application that makes the incoming authorization request.
  10. In the Group claim field, enter the name of the JWT claim that contains the groups that the client application sends as part of the authorization request. The Splunk platform uses the group claim to identify the groups that will have access to Splunk data when you map those groups to Splunk roles, as described in "Map groups from the client application on the identity provider to Splunk roles".
  11. (Optional) In the Full Name Claim field, enter the name of the JWT claim that contains the full name of the client that the client application sends as part of the authorization request. The Splunk platform uses the full name claim to provide a human-readable name for the client that makes the incoming request.
  12. Select Save.
The Splunk platform saves the new configuration and reloads the OAuth 2.0 configurations page with the new configuration in the list.

Map groups from the client application on the identity provider to Splunk roles

When you create a new OAuth 2.0 configuration, you must map groups that your Splunk platform instance receives in tokens that come from the client application on the identity provider to roles on the Splunk platform. This procedure lets the Splunk platform provide the client application access to Splunk data.

You must already have defined at least one OAuth 2.0 authorization server configuration.
  1. From the OAuth 2.0 Configurations page, under Configuration Name, select the OAuth 2.0 configuration where you want to map groups from the IdP to Splunk roles. The configuration page for that configuration loads.
  2. Under Role Mapping, select + New Mapping. The New Role Mapping page appears.
  3. In the Group Name field, enter the name of the group to which this Splunk platform instance is to map Splunk roles. The Group comes from the IdP client application as part of the Group claim in the authorization request that the client application sends.
  4. For each Splunk role that you want this group to map to, select it in the Available Roles column. You can map a group to one or more Splunk roles.
  5. Note: Only select roles that allow access to the Splunk data you want the client application to have.
    Select the > box between the Available Roles and Selected Roles columns to move the selected roles to the Selected Roles column.
  6. Note: To remove Splunk roles from the group mapping, select the roles that you want to remove in the Selected Roles column then select the < box to remove the selected roles.
    Save the group-to-role mapping. If you want to save the current group-to-role mapping, but have more changes that you need to make, select Save and Add More. Otherwise, select Save and Close.
The Splunk platform saves the group-to-role mapping. When it receives the JSON Web Token from the IdP client application, it maps the specified groups within the token to Splunk roles based on the information it receives in the group claim.