|
| 1 | +--- |
| 2 | +title: Bulk onboarding of users in HPE GreenLake edge-to-cloud platform |
| 3 | +date: 2024-04-24T13:44:40.533Z |
| 4 | +author: Didier Lalli |
| 5 | +authorimage: /img/didier-lalli.png |
| 6 | +disable: false |
| 7 | +tags: |
| 8 | + - API |
| 9 | + - hpe-greenlake |
| 10 | + - hpe-greenlake-platform |
| 11 | +--- |
| 12 | +<style> |
| 13 | +li { |
| 14 | + font-size: 27px; |
| 15 | + line-height: 33px; |
| 16 | + max-width: none; |
| 17 | +} |
| 18 | + |
| 19 | +ol li{ |
| 20 | + font-size:27px; |
| 21 | +} |
| 22 | +</style> |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | +## HPE GreenLake API to the rescue |
| 27 | + |
| 28 | +The use case covered in this document is part of what we call the Day 0 activities; tasks that must be done to onboard users to HPE GreenLake platform. When a customer decides to use HPE GreenLake, it is critical that all customer collaborators who require access to HPE GreenLake platform are invited to join. Using the HPE GreenLake console to invite hundreds of collaborators can be tedious and error prone - this is when an API comes to the rescue. The API allows you to write a script that reads a list of users from an Excel spreadsheet and automatically invites these users to access the HPE GreenLake platform. |
| 29 | + |
| 30 | +## What are the HPE GreenLake edge-to-cloud platform APIs |
| 31 | + |
| 32 | +The foundational APIs for common HPE GreenLake platform services allow IT administrators and IT operators to programmatically operate and manage users and resources in an HPE GreenLake platform workspace. |
| 33 | + |
| 34 | +This set of APIs for common platform services includes APIs for workspace management, identity and access management, device and subscription, locations, audit logs, and wellness. |
| 35 | + |
| 36 | +*Note: The [HPE GreenLake platform documentation](https://developer.greenlake.hpe.com/docs/greenlake/services/) for these APIs leverages OpenAPI specifications and associated reference material. The documentation provides a complete explanation of the operations supported by these APIs for common HPE GreenLake platform services, as well as sample requests and responses.* |
| 37 | + |
| 38 | +The following blog posts are an excellent way to learn more about the APIs using Postman: |
| 39 | + |
| 40 | +* [Get started with the foundational APIs for the HPE GreenLake edge-to-cloud platform – Part 1: Introduction to the APIs](https://developer.hpe.com/blog/get-started-with-the-foundational-apis-for-the-hpe-greenlake-edge-to-cloud-platform-%E2%80%93-part-1-introduction-to-the-apis/) |
| 41 | +* [Get started with the foundational APIs for the HPE GreenLake edge-to-cloud platform – Part 2: Configuring and managing a workspace](https://developer.hpe.com/blog/get-started-with-the-foundational-apis-for-the-hpe-greenlake-edge-to-cloud-platform-%E2%80%93-part-2-configuring-and-managing-a-workspace/) |
| 42 | +* [Get started with the foundational APIs for the HPE GreenLake edge-to-cloud platform – Part 3: Tracking activities and monitoring health](https://developer.hpe.com/blog/get-started-with-the-foundational-apis-for-the-hpe-greenlake-edge-to-cloud-platform-%E2%80%93-part-3-tracking-activities-and-monitoring-health/) |
| 43 | + |
| 44 | +In this blog post, I will focus on one specific API call, part of Identity Management. The call is `POST /identity/v1/users`, which invites users to an HPE GreenLake workspace. Full documentation on this API call can be found in the [HPE GreenLake developer portal](https://developer.greenlake.hpe.com/docs/greenlake/services/iam/workspaces/public/openapi/workspaces-v1/operation/invite_user_to_account_identity_v1_users_post/). |
| 45 | + |
| 46 | +## Providing the right data to the script |
| 47 | + |
| 48 | +Before writing any code, it’s important to understand what data is required to invite a user. You only need the email address of the invited user- that’s easy! In the [API reference](https://developer.greenlake.hpe.com/docs/greenlake/services/iam/workspaces/public/openapi/workspaces-v1/operation/invite_user_to_account_identity_v1_users_post/), you'll also see that there is no way to select a workspace to invite the user to. The reason for this is that the API credentials used to make the call is workspace specific, so it implicitly provides the workspace to which the user will be invited to. This means that you need to collect API access credentials for every workspace that you're adding users to. For the script I am writing here, in the Workspaces tab, I have stored the Client Id corresponding to API Access of a given Workspace. Because I don’t want to save Client Secrets, I will prompt for them and store them in memory. |
| 49 | + |
| 50 | +So, my Excel file contains the following 2 sheets: |
| 51 | + |
| 52 | + |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | +## High-level algorithm |
| 57 | + |
| 58 | +Let’s look at the steps necessary to invite users from my spreadsheets: |
| 59 | + |
| 60 | +1. Read command parameters to get the Excel filename |
| 61 | +2. Open spreadsheet to retrieve data |
| 62 | +3. For each workspace in Workspaces sheet |
| 63 | + * Prompt for Client Secret that matches the Client Id |
| 64 | + * Retrieve a session token using those credentials |
| 65 | +4. For each user in Users sheet |
| 66 | + * Lookup Client Id using workspace name |
| 67 | + * Call POST /identity/v1/users for user using email |
| 68 | + * Increase counter of invited users |
| 69 | +5. Display list of users invited in each workspace |
| 70 | + |
| 71 | +## Putting things together in PowerShell |
| 72 | + |
| 73 | +I decided to use PowerShell to write this script because it provides easy native access to Excel spreadsheets. |
| 74 | + |
| 75 | +### Step 1 – Reading the parameter from the command line. |
| 76 | + |
| 77 | +```powershell |
| 78 | +Param($XLFile) |
| 79 | +
|
| 80 | +if ($Null -eq $XLFile) |
| 81 | +{ |
| 82 | + if ($env:XLFile -eq $Null) |
| 83 | + { |
| 84 | + $XLFile = read-host "Enter name of the Excel file" |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +### Step 2 – Importing data from the 2 sheets of my spreadsheet. |
| 90 | + |
| 91 | +```powershell |
| 92 | +$tokens =@{} |
| 93 | +$invited=@{} |
| 94 | +
|
| 95 | +if ($XLFile) |
| 96 | +{ |
| 97 | + $users_excel = import-excel -path $XLFile -dataonly -worksheetname Users |
| 98 | + $workspaces_excel = Import-Excel -path $XLFile -dataonly -worksheetname Workspaces |
| 99 | +``` |
| 100 | + |
| 101 | +Note that I initialized 2 hash tables, one called $tokens that will store the token for a given Client Id (i.e Workspace) and another called $invited for storing the number of invited users for a given Client Id. |
| 102 | + |
| 103 | +### Step 3 – Iterating over the Workspaces sheet to collect client secrets, and retrieve access tokens. |
| 104 | + |
| 105 | +```powershell |
| 106 | +# Ask for client_Secret of each workspace in Excel file |
| 107 | + foreach ($workspace in $workspaces_excel ) { |
| 108 | + $client_id = $workspace.'Client Id' |
| 109 | + if ($tokens[$client_id] -eq $null) { |
| 110 | + # We don't have a token for this client_id yet |
| 111 | + # We need to ask the Client secret for this workspace |
| 112 | + $workspace_name = $workspace.'Workspace Name' |
| 113 | + $client_id = $workspace.'Client Id' |
| 114 | +
|
| 115 | + $secClientSecret = read-host "Enter HPE GreenLake Client Secret for Workspace $workspace_name" -AsSecureString |
| 116 | + $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secClientSecret) |
| 117 | + $secret = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr) |
| 118 | + |
| 119 | + # use Client Id and Client Secret to retrieve a token |
| 120 | + $body = "grant_type=client_credentials&client_id=" + $client_id + "&client_secret=" + $secret |
| 121 | + $headers = @{} |
| 122 | + $headers["Content-Type"] = "application/x-www-form-urlencoded" |
| 123 | + |
| 124 | + try { |
| 125 | + $response = Invoke-webrequest "https://sso.common.cloud.hpe.com/as/token.oauth2" -Method POST -Headers $headers -Body $body |
| 126 | + # store the token for future use |
| 127 | + $AccessToken = ($response.Content | Convertfrom-Json).access_token |
| 128 | + $tokens.Add($client_id,$AccessToken) |
| 129 | + } |
| 130 | + catch { |
| 131 | + Write-Host "Error retrieving access token for workspace $workspace_name!" -ForegroundColor Red |
| 132 | + exit |
| 133 | + } |
| 134 | + } |
| 135 | + } |
| 136 | +``` |
| 137 | + |
| 138 | +Note that, at the end of this loop, I have a hash table of tokens indexed by Client Id, which I will use to call the API in the next section. |
| 139 | + |
| 140 | +### Step 4 – Iterating over Users sheet to invite each of them. |
| 141 | + |
| 142 | +```powershell |
| 143 | +# Now walk the list of users to add |
| 144 | + $invited.Add($client_id,0) |
| 145 | + foreach ($user in $users_excel ) { |
| 146 | + $workspace_name = $user.'Workspace Name' |
| 147 | + # Get client id from workspace name |
| 148 | + $result = $workspaces_excel | Where-Object { $_.'Workspace Name' -eq $workspace_name } |
| 149 | + if ($result.Count -eq 0) |
| 150 | + { |
| 151 | + Write-Host "Workspace not found for user " $user.email -ForegroundColor Red |
| 152 | + exit |
| 153 | + } |
| 154 | + $client_id = $result[0].'Client Id' |
| 155 | + |
| 156 | + Write-Host "Inviting user" $user.email "to workspace./" $workspace_name |
| 157 | + $AccessToken = $tokens[$client_id] |
| 158 | +
|
| 159 | + # Create header for next API calls |
| 160 | + $headers = @{} |
| 161 | + $headers["Authorization"] = "Bearer $AccessToken" |
| 162 | + $headers["Accept"] = "application/json" |
| 163 | + $headers["Content-Type"] = "application/json" |
| 164 | + |
| 165 | + # Build body for next API call |
| 166 | + $_body = @{ |
| 167 | + "email" = $user.email |
| 168 | + "sendWelcomeEmail" = $true |
| 169 | + } |
| 170 | + |
| 171 | + $Body = $_body | ConvertTo-Json |
| 172 | + |
| 173 | + # Call GLP API to invite user |
| 174 | + try { |
| 175 | + $response = Invoke-webrequest -Uri "https://global.api.greenlake.hpe.com/identity/v1/users" -Method POST -Headers $headers -Body $Body |
| 176 | + $invited[$client_id]++ |
| 177 | + } |
| 178 | + catch { |
| 179 | + Write-Host "Error sending invite for" $user.Email"! Already onboarded?" -ForegroundColor Red |
| 180 | + Write-Host $Error[0] -ForegroundColor Red |
| 181 | + continue |
| 182 | + } |
| 183 | + sleep 15 |
| 184 | + } |
| 185 | +} |
| 186 | +``` |
| 187 | + |
| 188 | +Note that before the loop, I initialized to zero the count of invited users for a given workspace. Also note the sleep 15 (seconds) at the end of the loop to avoid issues with rate limiting constraints which might raise a status code 429. |
| 189 | + |
| 190 | +*Note: Rate Limiting is a mechanism employed to control and restrict the rate at which requests or interactions are permitted to occur between clients and a service.* |
| 191 | + |
| 192 | +### Step 5: Displaying list of users invited in each workspace. |
| 193 | + |
| 194 | +```powershell |
| 195 | +else |
| 196 | +{ |
| 197 | + write-host 'Mailing list file not provided nor found....' |
| 198 | + exit |
| 199 | +} |
| 200 | +Write-host "Done processing Excel file $XLFile!" |
| 201 | +
|
| 202 | +# ------------------------ Query GL to get list of users for each workspace ------------------------ |
| 203 | +foreach ($workspace in $workspaces_excel ) { |
| 204 | + $workspace_name = $workspace.'Workspace Name' |
| 205 | + $client_id = $workspace.'Client Id' |
| 206 | + # Create header for next API calls |
| 207 | + $headers = @{} |
| 208 | + $AccessToken = $tokens[$client_id] |
| 209 | + $headers["Authorization"] = "Bearer $AccessToken" |
| 210 | + $headers["Accept"] = "application/json" |
| 211 | + $headers["Content-Type"] = "application/json" |
| 212 | + try { |
| 213 | + $response = Invoke-webrequest "https://global.api.greenlake.hpe.com/identity/v1/users?filter=&limit=300&offset=0" -Method GET -Headers $headers |
| 214 | + } |
| 215 | + catch { |
| 216 | + Write-Host "Cannot get list of users!!" |
| 217 | + exit |
| 218 | + } |
| 219 | + $invited_users=$invited[$client_id] |
| 220 | + Write-Host $invited_users "user(s) invited to workspace" $workspace_name |
| 221 | + Write-Host "List of users in workspace:" $workspace_name |
| 222 | + |
| 223 | + $_list = $response.Content | ConvertFrom-Json |
| 224 | + if ($null -ne $_list) |
| 225 | + { |
| 226 | + $_users_list = [System.Collections.ArrayList]::new() |
| 227 | + |
| 228 | + foreach ($_u in $_list.Items) |
| 229 | + { |
| 230 | + |
| 231 | + $_users_list += @{ |
| 232 | + 'Username' = $_u.Username |
| 233 | + 'Status' = $_u.userStatus |
| 234 | + 'id' = $_u.Id |
| 235 | + } |
| 236 | + } |
| 237 | + |
| 238 | + } |
| 239 | + |
| 240 | + $_users_list | select Username, Status | ft -AutoSize |
| 241 | + |
| 242 | +} |
| 243 | +``` |
| 244 | + |
| 245 | +## Try it! |
| 246 | + |
| 247 | +Let’s run this script, making sure to reference the correct Excel spreadsheet: |
| 248 | + |
| 249 | +```markdown |
| 250 | +PS /Volumes/Dev/GreenLake/GLP-API-Tooling/Scripts> ./bulk_invite.ps1 -XLfile userlist.xlsx |
| 251 | +Enter HPE GreenLake Client Secret for Workspace HPEDEV -GLCP- Hackshack: ******************************** |
| 252 | +Enter HPE GreenLake Client Secret for Workspace Super Awesome Company: ******************************** |
| 253 | +Inviting user [email protected] to workspace HPEDEV -GLCP- Hackshack |
| 254 | +Inviting user [email protected] to workspace HPEDEV -GLCP- Hackshack |
| 255 | +Error sending invite for [email protected] ! Already onboarded? |
| 256 | +Inviting user [email protected] to workspace Super Awesome Company |
| 257 | +Inviting user [email protected] to workspace Super Awesome Company |
| 258 | +Error sending invite for [email protected] ! Already onboarded? |
| 259 | +Done processing Excel file userlist.xlsx! |
| 260 | + |
| 261 | +1 user(s) invited to workspace HPEDEV -GLCP- Hackshack |
| 262 | +List of users in workspace: HPEDEV -GLCP- Hackshack |
| 263 | + |
| 264 | +Username Status |
| 265 | +-------- ------ |
| 266 | +<email> VERIFIED |
| 267 | +… |
| 268 | + |
| 269 | +… |
| 270 | + |
| 271 | +… |
| 272 | +<email> VERIFIED |
| 273 | + |
| 274 | +1 user(s) invited to workspace Super Awesome Company |
| 275 | +List of users in workspace: Super Awesome Company |
| 276 | + |
| 277 | +Username Status |
| 278 | +-------- ------ |
| 279 | +<email> VERIFIED |
| 280 | +… |
| 281 | + |
| 282 | +… |
| 283 | + |
| 284 | +… |
| 285 | +<email> VERIFIED |
| 286 | +``` |
| 287 | + |
| 288 | +As you can see, the script has invited 1 user in each workspace. The second email address is already a member of the workspace, so no action is necessary. |
| 289 | + |
| 290 | +## What’s next? |
| 291 | + |
| 292 | +Through this post, I have shown you how it is possible to integrate with HPE GreenLake platform using the most popular scripting languages, such as PowerShell. You can get the source code for these scripts from [our community tooling repository](https://github.com/hpe-dev-incubator/GLP-API-Tooling). |
| 293 | + |
| 294 | +If you’re interested in trying out what I just discussed, you might first want to check out one of our hands-on Workshops-on-Demand that lets you play with the HPE GreenLake APIs mentioned in this blog post. The workshops are free, available 24/7, and very easy to use. They give you a real-world experience without any risk. Check out our [catalog of workshops](https://developer.hpe.com/hackshack/workshops), register for the one you’re interested in and go! It’s as simple as that. |
| 295 | + |
| 296 | +If you still have questions regarding the HPE GreenLake platform APIs, join the [HPE Developer Community Slack Workspace](https://developer.hpe.com/slack-signup/) and start a discussion on our [\#hpe-greenlake-api](https://hpedev.slack.com/archives/C02EG5XFK8Q) channel. We are always here to help. |
0 commit comments