Intro to Security

This sample is dedicated to helping users learn how to interact with GraphGrid Security. Learn how to get authorized to use the GraphGrid API with OAuth, create and update a user and password, and set user roles and security groups. Follow these steps in order for a complete walkthrough. Be sure to visit the Setup Guide to set your shell variables in order to follow along with the API requests more efficiently. This sample also serves as a guide for changing your superadmin password upon installation.

Get Authorized

In order to call the GraphGrid API we need to request an OAuth access token. OAuth requires client authentication in order to request an access token. To authenticate, generate a Basic Authorization header using client credentials. Client credentials consist of a client id and a client secret.

To generate a basic auth header, separate a client id and secret with a colon and then base64 encode them. Client credentials are configurable, however you may use the default values for a client id and secret:

'CLIENT_ID': 'a3847750f486bd931de26c6e683b1dc4'
'CLIENT_SECRET': '81a62cea53883f4a163a96355d47656e'

You can manually generate the authorization header in a terminal using the default client credentials:

echo -n 'a3847750f486bd931de26c6e683b1dc4:81a62cea53883f4a163a96355d47656e'| base64

After generating our encoded client credentials the full Basic Auth header will look like this:

Authorization: Basic YTM4NDc3NTBmNDg2YmQ5MzFkZTI2YzZlNjgzYjFkYzQ6ODFhNjJjZWE1Mzg4M2Y0YTE2M2E5NjM1NWQ0NzY1NmU=

Default username: graphgrid
Default password: graphgrid

Now we can request an OAuth access token running this request:

curl --location --request POST "${API_BASE}/1.0/security/oauth/token" \
--header "Authorization: Basic YTM4NDc3NTBmNDg2YmQ5MzFkZTI2YzZlNjgzYjFkYzQ6ODFhNjJjZWE1Mzg4M2Y0YTE2M2E5NjM1NWQ0NzY1NmU=
" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=graphgrid' \
--data-urlencode 'password=graphgrid'

Parameters

Key	Value	Description
grant_type	Either password or client_credentials	The grant type should be either client_credentials if authing for a client, or password if for a user
username	Username	The user username. Required if password is selected as grant_type above.
password	Password	The user password. Required if password is selected as grant_type above.
scope	all	Which OAuth scopes to request. Only all is available right now.

note

If you are getting started and changing your superadmin password this request will return your user grn as well as your auth token. Both of which you will need to update your password

After we've gotten our OAuth token, we can access the GraphGrid API and get started using GraphGrid Security!

Create User

To create a user account simply pass in the user's first and last name, email, username and password to this request:

curl --location --request POST "${API_BASE}/1.0/security/user/new?signIn=false&skipAllNotificationEmails=false" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--data-raw '{
    "firstName": "Graph",
    "lastName": "Master",
    "email": "GraphsRLife@graphgrid.test",
    "username": "GraphMaster",
    "password": "12345678",
    "role": 2
}'

note

To meet the security requirements, the password must be at least 16 characters and include one of each of the following: lower case letter, upper case letter, number, special character (!#$%&*+,-./:;<=>?@{|}~\"'()[]^`_)

Update User and Password Tutorial

To change a user's password, run this request:

note

A user with the role of SUPER ADMIN cannot change their password without their old password.

Base URL: /1.0/security/user/{{grn}}/updatePassword
Method: POST

Request

curl --location --request POST "${API_BASE}/1.0/security/user/grn:gg:user:HjdEQDeFQNkkpr0b6Hfo2Iozlil6XT36sJnz6r4OG6LT/updatePassword" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--data-raw '{
    "oldPassword": "12345678",
    "newPassword": "1SecureP@ssword"
}'

If successful, this request will return a 200 OK response.