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:
- SAML (RFC 7522)
- OAuth (RFC 6749)
- Open ID Connect
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.
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.
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.
It contains a proper access token you can use as a bearer token in requests.
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.
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.
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.
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.
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:
- 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