February 03, 2022

Let’s Git Commit(ted) to </Dev> Resources: Getting Started with the Workspace ONE Access APIs

Welcome back, Devs! Today we take a look at Workspace ONE Access and where you most likely interact with it. Access is all about user identities and access to resources, be it SSO into web applications with SAML and OIDC, or providing an intuitive user portal with Hub Services for a combined catalog, people search, and actionable notifications.

What is Workspace ONE Access?

Welcome back, Devs! Today we take a look at Workspace ONE Access and where you most likely interact with it. Access is all about user identities and access to resources, be it SSO into web applications with SAML and OIDC, or providing an intuitive user portal with Hub Services for a combined catalog, people search, and actionable notifications.

It is built using technologies such as:

If you are new to the product, you can find more details about Workspace ONE (WS1) Access at:

The Hub Services/Notification part will be covered in a later blog post, but for now, let’s delve into what can be done with Access itself. There are mostly 2 personas interacting on the API level. That is, developers trying to integrate their apps for SSO by either using SAML or OIDC, and administrators trying to automate tasks around auditing and user management.

Finding the right developer resources

For developers keen to incorporate SSO into their apps, you can either use existing frameworks based on SAML/OAuth, or have a look into our sample vidm-saml-toolkit, https://github.com/vmware/vidm-saml-toolkit. This toolkit hosts Java SDK sample code for the authentication flow, either as SP (Service Provider) or IDP with Access acting as SP.

A more modern approach is using OpenID Connect to authenticate and authorize users, as it works better on native mobile applications. Again on GitHub, we have a wiki that helps you explore the different authentication flows and how they fit certain application scenarios: https://github.com/vmware/idm/wiki/Choosing-The-Right-Auth.

Take note of Integrating Client Credentials app with OAuth2, which is also the main way to authenticate with Access APIs for administrators or DevOps.

Workspace ONE Access is mostly API-driven, so nearly everything you see and do in the user interface is a REST API. It should be a DevOps dream, but only a subset is documented and supported. That subset is concerned mostly with user management using System for Cross-domain Identity Management (SCIM), management of OAuth and OIDC tokens, a reports endpoint to retrieve auditing information around authentication, application access, and provisioning, as well as entitlement management.

The best resource for all our supported API and related information is developer.vmware.com, which houses the documentation for all our VMware products. All supported Workspace ONE Access API endpoints are documented in the VMware Identity Manager API section.

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

The website has a section that holds some sample code for all VMware products and Workspace ONE Access. For example, this code to move federated applications from Okta to Access or this sample showcasing how to use the API from PowerShell.

So those are the documented and supported APIs. As I mentioned, most of Workspace ONE Access is API-based, so more could be done like bulk operations. Examples of that can be found on flings.vmware.com, the Identity Manager Migration/Backup Tool, or the Workspace ONE Access Migration Tool to migrate configurations between test and production environments. Those APIs are not documented, but you can glean their usage by leveraging the Web Developer tools of your browser. Just check functions inside the UI and use the network tab to learn about the API endpoint, the HTTP verb used, header information like Accept and Content-Type, and the format of the data required in the request body.

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

Note: This is only for advanced users and is unsupported by VMware.

API in action, but how to authenticate

Obviously, access to the API, same as the GUI, is secured and only allowed for authorized requests. There are several ways to authenticate your API requests.

For one, you could use your normal admin user login data to get a token. You could get the access token by checking your browser session again with developer tools and looking for the HZN cookie.

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

It contains a proper access token you can use as a bearer token in requests.

bearer token decoded

You could also build a request to get the token in the REST API testing tool or script of your choice. See below for an example of how you could do that in Postman.

Text</p> <p>Description automatically generated

If you do a lot of work with the APIs or plan to write an app for it, you should use proper client credentials, which you can generate in Access as remote app access clients.

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

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

You can find more information about this as mentioned earlier, on the Github page: Integrating Client Credentials app with OAuth2 or in later iterations of this month-long blog series on how to use Postman.

We got a token to authorize now and can pick our API, but what makes up a REST API call and what other information do you need for your request?

  • API request URL (which endpoint to send the request to)
  • HTTP method  - GET, POST, PUT, DELETE, PATCH as the most common
  • Authentication  - Bearer, Basic, API key, NTLM
  • Request Headers  - with Access, each API other than SCIM have specific Headers for Content-Type and Accept
  • Content-Type - if you are sending a body(with POST, PUT, PATCH methods) with your request it marks the type of content in that body
  • Accept is the type that is acceptable in the response and needs to match what Access sends back if set
  • Request Query Parameters  - key-value pairs added to the HTTP request
  • Request Body  - in JSON, XML, or Forms format but with Access mostly JSON
  • Response HTTP Status Code – 2xx good and giving you a response, 4xx/5xx bad with something wrong in the request or server-side

With all that information, it is just down to picking the API; for example, listing a set of users on our tenant and creating our first request.

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

In Postman, that would be something like the following screenshot, with the response being JSON and listing all users on that tenant including all user attributes.

Text</p> <p>Description automatically generated

Real-world examples

The flings on labs.vmware.com mentioned earlier show you some of the bulk actions possible.

But another great example of using the APIs is Rollcall by Pete Lindley, a middleware to provision users from SCIM 2.0 sources like Azure AD into Access which uses SCIM 1.1 so far. Learn more at https://github.com/tbwfdu/rollcall and https://github.com/tbwfdu/rollcall-google.

Or an Android app for Access admins also by Pete Lindley, https://play.google.com/store/apps/details?id=com.tbwfdu.swat.

Wrap up

This hopefully gives you an idea of the that APIs Workspace ONE Access provides, and where to learn more about them. One of the most interesting areas is certainly SCIM and user provisioning and management, where we aim to introduce improvements with future product enhancements adding support for SCIM 2.0. Another interesting area is the reporting API, which allows you to bring all the auditing done by Access around user logins into your SIEM or security tools.

What’s Next

Be sure to subscribe to the Digital Workspace Tech Zone Blog RSS or check back daily to see what we release. By the end of this month, we hope that you are comfortable leveraging code samples, VMware Flings, scripting/coding, and leveraging the EUC APIs to automate your workspace!

You can also follow us on Twitter @EUCTechZone to stay updated on the latest EUC content!

Agenda

And 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

Sascha Warno

Read More from the Author

Staff Solutions Architect - Identity & Security, EUC Technical Marketing, VMware. Sascha has been with VMware for 8 years having joined through the AirWatch acquisition, mastering Workspace ONE UEM before shifting focus to Identity & Access Management as well as Security. He provided his expertise in Sales, Customer Success and nowadays shares his knowledge and experience about using VMware's solutions for security and access management as part of the EUC Tech Marketing team.