Authentication

Curl takes username and password for Basic Auth through the -u, --user option. Username and password need to be separated by a colon.

curl "https://api.aedifion.io/v2/user" 
    -u john.doe@aedifion.com:s3cur3p4ssw0rd

There are several ways to set Basic Auth credentials in Postman. Preferably, you should set up authentication within a dedicated environment. In this environment, add variables email (or username) and password.

Figure 1: Manage environments in Postman

On your collection (left pane), click the three dots and choose Edit from the drop-down and navigate to the Authorization tab. Choose Basic Auth as type and enter variables {{ email }} and {{ password }} as email and password, respectively. These variables will be replaced with the actual values defined in your environment.

Figure 2: Edit collections in Postman

Note that you can also define this individually per request if you do not want to use the same authentication method and credentials for all requests in your collection.

By redefining baseurl, email and password variables in different environments, you can quickly switch APIs and users just by switching the environment from the dropdown on the top right.

Figure 3: Switch environment from the dropdown

The Swagger UI is an interactive UI for the aedifion HTTP API auto-generated from the API's OpenAPI specification.

1. Open https://api.aedifion.io/ui/ in a browser.
2. Click "Authorize" on the top right.
3. In the pop-up, enter username and password in the respective fields. Swagger UI will cache your credentials on your device until you close the browser tab.
4. Click the bottom "Authorize" button. Note that the Swagger UI does not actively check the validity of your credentials at this point. You will only notice on your first request if you entered wrong credentials.
5. Drop down the "User" section and choose the GET /v2/user endpoint.
6. Click "Try it out!"

Figure 1: Swagger UI authorization

In Python, the excellent requests module takes Basic Auth credentials formatted as a tuple of username and password through the optional keyword parameter auth:

import requests

api_url = "https://api.aedifion.io"
auth_john = ("john.doe@aedifion.com", "mys3cr3tp4ssw0rd")
r = requests.get(f"{api_url}/v2/user", auth=auth_john)

In this example, we use OIDC's "Direct Access Grant" to obtain an access token directly from the Identity Provider.

1. Obtain the token and store it in a local variable.
2. Pass the obtained token as Bearer Token in the HTTP authorization header to authenticate the API request.

## Lines 3-10 are formatted in multiple lines for better readability. 
## Remove newlines before pasting to the command line.
TOKEN=$(curl -X POST 
             -H "Content-Type: application/x-www-form-urlencoded" 
             -d "grant_type=password"
             -d "client_id=tutorial-curl"
             -d "username=john.doe@aedifion.com"
             -d "password=s3cur3p4ssw0rd" 
             "https://auth.aedifion.io/auth/realms/aedifion/protocol/openid-connect/token" 
       | jq -r '.access_token')
curl -H "Authorization: Bearer ${TOKEN}" "https://api3.aedifion.io/v2/user"

There are several ways to set OIDC-based authentication in Postman. Preferably, you should set up authentication once for your collection and not per individual request.

On your collection (left pane), click the three dots and choose "Edit" from the drop-down and navigate to the "Authorization" tab. Choose OAuth 2.0.

Figure 1: OAuth 2.0 authorization

Now click "Get New Access Token" and fill in the following settings (the full Auth URL is https://auth.aedifion.io/auth/realms/aedifion/protocol/openid-connect/auth):

• Token Name: Choose one, e.g., "aedifion API"
• Grant Type: Implicit
• Callback URL: https://www.getpostman.com/oauth2/callback
• Auth URL: https://auth.aedifion.io/auth/realms/aedifion/protocol/openid-connect/auth
• Client ID: postman
• Client Authentication: Send as Basic Auth header

Figure 2: Get a new access token

Click "Request Token". This will kick-off an OAuth 2.0 "Implicit Grant" which redirects you to the login form of the aedifion Identity Provider within a browser-like window directly within Postman. Enter your credentials and login. You will be redirected back to Postman.

Having successfully logged-in, the obtained token will be displayed on the right, and a list of all (previously) obtained tokens on the left. Just close this window for now.

Finally, on the Authorization tab of your collection settings (which should be still open) select the token you've obtained a moment ago from the "Available Tokens" drop-down menu. Click "Update" to finish. You're now ready to fire off your requests to the API - just make sure to not unintentionally override Authorization on request-level.

For more information, see https://learning.getpostman.com/docs/postman/sending-api-requests/authorization/#oauth-20.

The Swagger UI is an interactive UI for the aedifion HTTP API auto-generated from the API's OpenAPI specification.

1. Open https://api.aedifion.io/ui/ in a browser.
2. Click "Authorize" on the top right. This will kick off OIDC's "Implicit flow".
3. In the pop-up, ignore the username and password fields and just click the top "Authorize" button. You will be redirected to aedifion's Identity Provider and prompted to log in.
4. On the log in form, fill in your email/username and password. Click "Log in". You will be redirected back to the application (i.e., the Swagger UI).
5. Drop down the "User" section and choose the GET /v2/user endpoint.
6. Click "Try it out!".

Figure 1: Swagger UI OAuth 2.0 authorization

Figure 2: Log In

Example: Direct Access Grant

We start off with a simple example that uses OIDC's "Direct Access Grant" and is equivalent to the Curl example.

import requests

# Get an access token from the IP
data = {
    "username": "john.doe@aedifion.com",
    "password": "s3cur3p4ssw0rd",
    "grant_type": "password",
    "client_id": "tutorial-python"
}
r = requests.post("https://auth.aedifion.io/auth/realms/aedifion/protocol/openid-connect/token",
                  data=data)  # data will be automatically form-encoded
access_token = r.json()["access_token"]

api_url = 'https://api.aedifion.io'
# Make the actual request and print the results
r = requests.get(f"{api_url}/v2/user", 
                 headers={"Authorization": f"Bearer {access_token}"})
print(f"{r.status_code} - {r.text}")

Note that the "Direct Access Grant" used in the above example requires the user to provide username and password to the Python script. In real-world production-grade applications, this is considered insecure in most usage scenarios and should be avoided.

Example: Implicit Flow

As a better alternative, we now use OIDC's full fledged "Authentication Code Flow" in the next examples which redirects the user to the Identity Provider for login and thus does not require the user to entrust the application with his/her credentials.

In the "Authentication Code Flow", unlike the "Implicit Flow", the user receives only an authorization code after login that he/she has to exchange for an access token (and a refresh token and, optionally, an id token) in a subsequent step.

Since the "Authentication Code Flow" requires a lot more legwork than suitable for a short concise example, we provide a lot of the boiler plate code in the oidc-client.py script in aedifion's public repository of code samples.

Go ahead and download that script and install the required modules. Then run the example by:

python3 oidc-client.py -c tutorial-python

The script will open a browser and prompt you to log in to aedifion's Identity Provider. After login, you'll receive an authorization code that you need to input to the python script. The script will then exchange it for an identity, refresh and access token and issue an actual API request.

Note that the obtained tokens are stored in your home directory under folder .aedifion/ after the first login. Any subsequent run of oidc-client.py will find a previously obtained token, so that you do not have to log in again.