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 provides a secure authorization method that lets administrators share access to resources without having to provide local credentials to external consumers of those resources. The Splunk platform leverages your OAuth server as the authentication and authorization source, which lets all authorization happen there from the client application identity that you define and manage.

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 OAuth server, which they use to connect to the Splunk platform.

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

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

After you register the OIDC server on the Splunk platform instance:

  1. The client application authenticates against the OAuth server using its client credentials and receives an OAuth access token.

  2. The client application, through the OAuth server, exchanges the OAuth access token for a Splunk access token.

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

Example for configuring an external OAuth server

You are a Splunk administrator and need to activate a bespoke application to fetch data from your Splunk platform instance to perform some analysis. You currently have a local user account with a username and password which this application uses. Compliance requirements for your organization have recently changed, and you can no longer use local Splunk user accounts. You must now use OAuth 2.0 as a replacement for the local user.

You access your Splunk platform instance and add your OAuth server. This creates a trust between your OAuth server and your Splunk platform instance. Using the OAuth server, you provision an OAuth client for your application. You provide the OAuth Client ID and secret to your developer as well as the Splunk token endpoint URL.

The application developer modifies the application to call your OAuth server with the provided Client ID and secret and receives an OAuth access token. The application then calls the Splunk token endpoint URL to exchange the OAuth access token for a Splunk token. Because the Splunk platform trusts the OAuth provider, the application receives a Splunk OAuth access token and uses that token for all API calls. This now replaces the local user account, which you can delete.

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) URI from the client application. The administrator provides this information. If you are the administrator, then you must set up and retrieve this information during client registration.

  • 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 URI field, enter the URI 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 or list 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 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 to which you want this group to map, select the role 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.