February 12, 2022

What is OAuth - Learning the Basics

Welcome to day 12 of Let’s Git Commit(ted) to </Dev> Resources! Today’s topic will explore the concepts and basics of OAuth, how it is used in some Workspace ONE APIs, and additional resources for further learning. Let’s get started!

Welcome to day 12 of Let’s Git Commit(ted) to </Dev> Resources! Today’s topic will explore the concepts and basics of OAuth, how it is used in some Workspace ONE APIs, and additional resources for further learning. Let’s get started!

What is OAuth?

OAuth (Open Authentication) is an Authorization Framework standard (RFC 6749) that provides secure delegated access to client applications. There are two versions of OAuth – OAuth 1.0a and OAuth 2.0. However, OAuth 2.0 is the current standard, so we will only be focusing on OAuth 2.0 in this discussion.

So, what is secure delegated access, and why should we care? OAuth 2.0’s site has a feature video called Why Do We Really Need OAuth Anyway by Aaron Parecki that describes this problem beautifully. To steal Aaron’s example of why OAuth is important, think of when you get a hotel key card when staying at a hotel. The key card allows you to get into your room and perhaps a few other shared areas of interest such as dining areas, gyms, or a parking deck. The key card doesn’t allow you to go into other people’s rooms – that would be a catastrophic security flaw! It also doesn’t allow you to go to secure locations in the building, such as maintenance areas, where guests could get hurt.

In OAuth terms, the hotel key card would be the access token. This access token authorizes the service to perform specific actions. In the hotel example, the access token is the key card that opens the door. The limit that the access token is authorized for is called the scope. In the hotel example again, the scope determines which doors the key card can open. We don’t want our guests to open every door, so we limit the scope to the intended rooms.

Refresh tokens are another component of OAuth that allow a client to get a new access token without the user’s interaction. This allows a new access token with the same scope to be retrieved without requiring manual user interaction.

Authorization vs. Authentication

OAuth provides authorization, not authentication. What’s the difference?

Authorization defines the permissions around a task, such as what data can or cannot be accessed.

Authentication is used to identify the user by requiring they prove who they are with a password, certificate, or some other authentication method to prove their identity.

In the hotel example, the key card has the authorization to open a door independently of who is holding it. The key card functions the same no matter who holds it and uses it – it doesn’t know who the holder is. The hotel staff authenticates who you are at the front desk by requesting identifying documents.

OAuth is not a replacement for authentication. It is only intended to provide authorization.

Client ID and Client Secret

The client ID (client identifier) is a public identifier for an application. The client secret is a secret that is only known to the client application and the authorization server. You should think of the client ID like a username and the client secret like a password, and should therefore not store these values in plain text.

It’s not uncommon for the client secret to only be shown once when it is generated, and then not provide a way to retrieve this value again in the future. If you lose the client secret, you will need to regenerate a new one, which will invalidate any clients that attempt to authorize an access token with the previous secret.

If Client Secrets are like Passwords, then why use OAuth?

OAuth authorizes a service permission to do something on your behalf without needing to use your account credentials. Instead, it uses the scope to limit what it can perform, and then allows apps to authenticate using the client id and client secret.

Why is this important? Here’s another example of Aaron’s – you found a new app and want to see if any of your email contacts also use the app. Consider the two options:

  1. You provide your email account password to look up the contacts. Sure, the app has promised you that it will only use your credentials to authenticate and retrieve your contacts, but how can you be sure? You are granting full account access by providing your email. The service could send mail, read mail, or do anything else with your credentials.
  2. The app uses OAuth to authorize an access token which has a scope limited to reading your contacts. In this approach, the returned access token can only retrieve contacts, since any attempt to use the access token for other means, like reading your emails, would return a 401 Unauthorized response or similar, indicating that the token doesn’t have the necessary permission to perform the requested action.

Option 2 grants secure delegated access to the app and the user can rest easy, knowing that the access token will only have the ability to access the requested scopes.

How does this all apply to Workspace ONE?

Workspace ONE UEM has three methods for authentication with REST APIs: Basic Authentication (username and password), Certificate Authentication, and OAuth. Using OAuth for the REST APIs provides tremendous security benefits over basic authentication, as described above, and should be used instead of basic authentication.

Let’s see how to set up OAuth in Workspace ONE UEM and how to authorize an API call with it!

NOTE: OAuth is only available in Workspace ONE UEM SaaS environments.

Setting up REST API OAuth authentication in Workspace ONE UEM

Here's how to set up OAuth in Workspace ONE UEM and use it to authorize an API call.

Step 1. Create an OAuth Token

Graphical user interface, application</p> <p>Description automatically generated

Figure 1: Workspace ONE UEM Configurations page

  1. In the Workspace ONE UEM Administrator Console, navigate to Groups & Settings > Configurations.
  2. Search for OAuth and select OAuth Client Management.
  3. Click Add to create a new OAuth client ID and secret.

Graphical user interface, text, application, email</p> <p>Description automatically generated

Figure 2: Registering an OAuth Client

  1. Configure the new OAuth Client details:
    1. Name: Provide a friendly name to identify the client.
    2. Description: Provide an optional description of the client.
    3. Organization Group: Select which organization group this OAuth client will be allowed to manage.
    4. Role: Select the role that the OAuth client will have the privileges of (this determines the scopes available to the access token).
    5. Status: Leave enabled to allow this service to create and refresh access tokens.
  2. Click Save when finished.

Graphical user interface, text, application, email</p> <p>Description automatically generated

Figure 3: Confirm the OAuth client, and save the client ID and client secret values

  1. The client ID and client secret are displayed here.
    CAUTION: Make sure to copy the client secret value somewhere safe as it cannot be viewed again once you leave the page!
  2. Click Close.

You now have a client ID and client secret that can be used to obtain an access token to authorize Workspace ONE UEM REST APIs.

Step 2. Request an Access Token

You need three things to generate an access token:

  1. The client ID
  2. The client secret
  3. The token URL

We have the client ID and secret, but still need the token URL. You can find the token URL for your SaaS datacenter by referencing the region-specific token URLs table. In my example, I am working from a UAT environment, so I will use the Ohio (United States) region token URL, for example, https://uat.uemauth.vmwservices.com/connect/token.

Be sure to copy the region-specific token URL for your environment and format your API request as follows, making sure to replace the {{REGION}}, {{CLIENT_ID}} and {{CLIENT_SECRET}} placeholders:

URL

POST https://{{REGION}}.uemauth.vmwservices.com/connect/token

Headers

No headers

Body

Send the following form-data in the body:

@{

    grant_type = “client_credentials”

    client_id = {{CLIENT_ID}}

    client_secret = {{CLIENT_SECRET}}

}

 

If using Postman…
  1. Select the Body tab
  2. Select the form-data format
  3. Enter each key value pair above in the respective key and value fields

If using a script…

You will need to check how to format a form-data post body in the language of your choice.

 

See Brooks Peppin’s PowerShell sample.

 

On a successful request, you will receive the following response:

Status Code

200 OK

Body

{

    "access_token": "************",

    "expires_in": 3600,

    "token_type": "Bearer",

    "scope": "uem-api"

}

I have omitted the access_token token from the response, but make sure to store your returned value for the next step. The response gives us several important details:

  • The access token (access_token) to be used in future requests to authorize the REST APIs.
  • The time in seconds (expires_in) that the token is valid for before a new token must be requested. In this case, 3600 seconds = 1 hour.
  • The token type (token_type) that must be supplied in future requests to authorize the REST APIs.

Step 3. Making a Workspace ONE UEM REST API Request with an Access Token

Let’s revisit an API from Day 2’s Getting Started with the Workspace ONE UEM REST APIs with Scot Curry – the /system/groups/search API as an example.

Previously, Scot needed to provide the following headers to authorize the API request:

  1. aw-tenant-code: The REST API key retrieved from the Workspace ONE UEM REST API settings
  2. Authorization: The base64 encoded administrator username and password that was authorizing the REST API

We will be able to omit the aw-tenant-code header and just provide the Authorization header with the following format: Bearer {{access_token}}. We will also still need provide the Accept and Content-Type headers to indicate if we are working with JSON (application/json) or XML (application/xml).

Here’s what our request looks like now, taking care to replace the following placeholders:

  • {{UEM_API_URL}} the Workspace ONE UEM REST API of your instance
  • {{access_token}} the access token received from step 2

URL

GET https://{{UEM_API_URL}}/api/system/groups/search

Headers

Key

Value

Authorization

Bearer {{access_token}}

Accept

Application/json

Content-Type

application/json

 

Body

None

On a successful request, you will receive a 200 OK and retrieve the organization group records just as Scot was able to do when providing the aw-tenant-code and Authorization basic headers!

Conclusion and Next Steps

What a productive session! In review, you’ve learned:

  1. What OAuth is at a high level
  2. Why it is more secure than traditional Basic authentication using username and password
  3. How to set up an OAuth client in Workspace ONE UEM
  4. How to retrieve an access token for use with Workspace ONE UEM REST APIs
  5. How to format the headers to include the bearer access token with Workspace ONE UEM REST APIs

For additional reading on OAuth, I recommend Aaron Parecki’s OAuth 2.0 Simplified website and his Why Do We Really Need OAuth Anyway video.

For more information on Workspace ONE UEM REST API roles, check out our documentation here.

If you enjoyed this API overview and want to see more examples or a deeper dive – let us know!

Agenda

Make sure to check out the other blog posts in our 28-day series:

 

Filter Tags

Workspace ONE Workspace ONE Access Workspace ONE Intelligence Workspace ONE UEM Blog Technical Overview Intermediate Optimize

George Spelvin

Read More from the Author

Multi-Cloud Computing Guru, VMware. George has been working as a VMware guru since time began. People say that he actually does very little and exists solely to claim ownership of work produced by people that have gone before. Thankfully, we only pay him in kibble. George never attended university, and has never been seen in the office or on a Zoom call. He is a good boy.