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!
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:
- 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.
- 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
Figure 1: Workspace ONE UEM Configurations page
- In the Workspace ONE UEM Administrator Console, navigate to Groups & Settings > Configurations.
- Search for OAuth and select OAuth Client Management.
- Click Add to create a new OAuth client ID and secret.
Figure 2: Registering an OAuth Client
- Configure the new OAuth Client details:
- Name: Provide a friendly name to identify the client.
- Description: Provide an optional description of the client.
- Organization Group: Select which organization group this OAuth client will be allowed to manage.
- Role: Select the role that the OAuth client will have the privileges of (this determines the scopes available to the access token).
- Status: Leave enabled to allow this service to create and refresh access tokens.
- Click Save when finished.
Figure 3: Confirm the OAuth client, and save the client ID and client secret values
- 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! - 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:
- The client ID
- The client secret
- 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}} }
|
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:
aw-tenant-code
: The REST API key retrieved from the Workspace ONE UEM REST API settings- 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 |
|
||||||||
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:
- What OAuth is at a high level
- Why it is more secure than traditional Basic authentication using username and password
- How to set up an OAuth client in Workspace ONE UEM
- How to retrieve an access token for use with Workspace ONE UEM REST APIs
- 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:
- Day 1: Let's Git Commit(ted) to Dev Resources
- Day 2: Getting Started with the Workspace ONE UEM REST APIs
- Day 3: Getting Started with the Workspace ONE Access APIs
- Day 4: Getting Started with the VMware Workspace ONE Intelligence APIs
- Day 5: Getting Started with the VMware Horizon REST APIs and VMware PowerCLI
- Day 6: Getting Started with Automating the Unified Access Gateway Deployment
- Day 7: Podcast: Day 0 Onboarding Automation with Scot Curry
- Day 8: Video: Anatomy of the Workspace ONE UEM API
- Day 9: Introduction to using Postman - Part 1
- Day 10: Introduction to using Postman - Part 2
- Day 11: Pro Tips and Tricks - How to be an API Boss
- Day 12: What is OAuth - Learning the Basics
- Day 13: Getting Started with Intelligent Hub Notifications
- Day 14: Git Basics: Getting Git Going
- Day 15: Podcast: Git Commit(ted) to Resources: Customer Spotlight with The Home Depot
- Day 16: Git VMware {code} Samples and Flings
- Day 17: Using paginated requests with Workspace ONE UEM REST APIs
- Day 18: Event Notifications
- Day 19: Overview of Script Samples using PowerCLI for Horizon
- Day 20: Uploading Windows apps using REST APIs
- Day 21: Uploading macOS apps using REST APIs and Admin Assistant
- Day 22: API-based user lifecycle and SCIM
- Day 23: Video: Community Expert Roundtable on Leveraging APIs and Scripting
- Day 24: Video: Exploring the Workspace ONE GitHub Samples Repository
- Day 25: Featured Fling: Forklift for Workspace ONE UEM
- Day 26: Featured VMware {code} Samples for Horizon
- Day 27: Featured Flings for VMware Horizon
- Day 28: Continuing to Focus on </Dev> Resources Page