Endpoint Authorization
Security Context
Authorization for GraphGrid API endpoints is primarily determined by client and user roles, though some endpoints do use OAuth2 scopes. A list of endpoints and required roles is available here.
In this document, a "client" will refer to an OAuth API client with an associated client id/secret. Clients are used to obtain an authorization grant and access token, which users can then use to make API requests.
If you would like to check the roles and scope associated with an OAuth token, the check token
endpoint can be used to examine the token's security context. When authenticating using user credentials and the /1.0/security/oauth/token
endpoint, client credentials are also required. Any roles associated with the client id and secret used will
then become associated with the user's OAuth token. For example, if a client with ROLE_CLIENT_INTERNAL is used to
authenticate a user with ROLE_USER, the returned OAuth token will have a security context with both ROLE_CLIENT_INTERNAL
and ROLE_USER.
Please note that security groups and roles are completely different. Security groups are used to enforce authorization requirements for dynamic Showme endpoints in GraphGrid's Manager service. Roles are used for authorization throughout GraphGrid with non-Showme endpoints.
Roles for users accounts can be modified by users with the role ROLE_SUPER_ADMIN using these endpoints.
While API clients can be created, deleted, and updated using these endpoints,
modifying roles require connecting to the LDAP service directly.
LDAP
GraphGrid uses OpenLDAP to hold user and client credentials. Before trying
to connect, please ensure the openldap service has port 389 exposed. We recommend using Apache Directory Studio
to connect to the LDAP server. Connect using "Simple Authentication" with cn=admin,dc=graphgrid,dc=com as the "Bind DN". The LDAP
admin password can be found in the GraphGrid data directory in data/env/openldap.env.
Roles exist in LDAP as group membership attributes. User roles can be modified using the previously mentioned endpoints, or by changing group membership directly in LDAP. Client roles can only be modified through LDAP.
Default Client
The default client that ships with GraphGrid has publicly exposed credentials
to accommodate requests from the GraphGrid Curator dashboard. We highly recommend locking down or removing the
default client, and creating one with a new secret that fits your specific organizational needs. Some endpoints
can be called with a client_credentials grant type, so please keep that in mind when determining your client roles.
If you do end up changing your client credentials, you'll need to provide your updated credentials to the
Curator dashboard. The dashboard code is stored inside the custom NGINX image that ships with GraphGrid.
Simply copy the file at /var/www/viz/config.js (inside the NGINX container), and override it using a Docker
bind mount.