To make an authenticated request, you must authenticate as a specific User.
There are three authentication mechanisms available when invoking web APIs:
Basic Authentication: Sends the user credentials as an encoded user name and password pair. This is the simplest authentication protocol (available since HTTP/1.0), but should be used only for development purposes, as it’s insecure.
OAuth 2.0: In Liferay DXP 7.2, you can use OAuth 2.0 for authorization. See the OAuth 2.0 documentation for more information.
Cookie/Session authentication: From inside the portal you can do direct requests to the APIs by sending the session token.
First, you’ll learn how to send requests with basic authentication.
Basic authentication requires that you send an HTTP
containing the encoded user name and password. You must first get that encoded
value. To do so, you can use
openssl or a
Base64 encoder. Either way, you
must encode the
user:password string. Here’s an example of the
command for encoding the
user:password string for a user
with the password
openssl base64 <<< email@example.com:Liferay
This returns the encoded value:
If you don’t have
openssl installed, try the
base64 <<< firstname.lastname@example.org:Liferay
Use the encoded value for the HTTP Authorization header when sending the request:
curl -H "Authorization: Basic dGVzdEBsaWZlcmF5LmNvbTpMaWZlcmF5Cg==" http://localhost:8080/o/graphql ...
The response contains data instead of the 403 error that an unauthenticated request receives. For more information on the response’s structure, see Working with Collections of Data.
Liferay DXP 7.2 supports authorization via OAuth 2.0, which is a token-based authorization mechanism. For more details, see Liferay DXP’s OAuth 2.0 documentation. The following sections show you how to use OAuth 2.0 to authenticate web API requests.
Before using OAuth 2.0 to invoke a web API, you must register your application (your web API’s consumer) as an authorized OAuth client. To do this, follow the instructions in Creating an Application. When creating the application, fill in the form as follows:
Application Name: Your application’s name.
Client Profile: Headless Server.
Allowed Authorization Types: Check Client Credentials.
After clicking Save to finish creating the application, write down the Client ID and Client Secret values that appear at the top of the form.
Next, you must get an OAuth 2.0 access token. To do this, see Authorizing Account Access with OAuth 2.
Once you have a valid OAuth 2.0 token, include it in the request’s
Authorization header, specifying that the authentication type is a
curl -H "Authorization: Bearer d5571ff781dc555415c478872f0755c773fa159" http://localhost:8080/o/graphql
The response contains the resources that the authenticated user has permission
to access, just like the response from Basic authentication. The request could
be prevented depending on the scopes defined. If POST a GraphQL query
and there is scope disabling all request except
GET, you see a 403.
You can call the GraphQL APIs using the existing session from outside the Liferay DXP by passing the session identifier (the cookie reference) and the Liferay Auth Token (a CSRF—Cross-Site Request Forgery—token).
To make an unauthenticated request from outside the Liferay DXP you must
Cookie identifier in the header:
curl -H 'Cookie: JSESSIONID=27D7C95648D7CDBE3347601FC4543F5D'
You must also provide the CSRF token by passing it as a query parameter
p_auth or by adding the URL to the whitelist of CSRF allowed URLs or disabling CSRF
checks altogether with the
auth.verifier.auth.verifier.PortalSessionAuthVerifier.check.csrf.token property (application level).
Here’s a sample cURL request with the cookie and CSRF token:
curl -H 'Cookie: JSESSIONID=27D7C95648D7CDBE3347601FC4543F5D' http://localhost:8080/o/graphql?p_auth=O4dCU1Mj
Unauthenticated requests are disabled by default in Liferay DXP’s GraphQL APIs. As all GraphQL APIs share the same endpoint, you cannot have the same level of granularity with Service Access Policies as in REST APIs. For that reason, we do not recommend disabling the security of the GraphQL APIs.