andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Calling a protected API from a .NET 8 Blazor Web App can be a bit tricky. Let's see what the problems are and how to solve them.

Call Protected APIs from a Blazor Web App

Pradheepa Pullanieswaran

Pradheepa Pullanieswaran is a Developer Advocate at Okta, with a real love for backend and open-source technologies. She has worked in enterprise and web technologies for over a decade and now on the journey of helping developers to better secure their application. She is also an active member of Women Who Code and mentors women to step into the software industry. She loves to read and spends time with her family in her spare time.

Staff Developer Advocate

Web Authentication API (WebAuthn) is a W3C and FIDO specification that allows registration and authentication of users using public key cryptography instead of a password.

## Introduction

WebAuthn (Web Authentication) is an API specification by W3C that facilitates a secure way for users to log in to online services and websites using various authentication methods, such as biometrics (e.g., fingerprint or facial recognition) and hardware-based authenticators (e.g., USB or NFC tokens). 

## Key Features of WebAuthn

### Phishing resistant

WebAuthn uses [public key cryptography](https://auth0.com/blog/how-to-explain-public-key-cryptography-digital-signatures-to-anyone/); the user's private key never leaves their device. Since WebAuthn relies on cryptographic keys, it is resistant to phishing attacks. Assuming that a bad actor tricks the user into entering their credentials on a phishing site, the attacker cannot use those credentials because they are scoped to a specific domain. In short, a credential created for `webauthn.me` cannot be used by a fake website, `webauth.me`. According to [Verizon DBIR 2023](https://www.verizon.com/business/resources/reports/2023-data-breach-investigations-report-dbir.pdf), Phishing is one of the major attacks on a web-based application, as shown in the following image. Using WebAuthn, the web applications could have easily averted these attacks. 
   
#### Action varieties in Social Engineering incidents

![Action varieties in Social Engineering incidents](https://images.ctfassets.net/23aumh6u8s0i/EAHiNaQrRaclMm2OnR1TA/cc50a06eef6af456d6a02f74731d4f6e/Phishing_DBIR.png)
 
### High-Security standards 

WebAuthn leverages industry-standard cryptographic algorithms and protocols to ensure the highest level of security. It utilizes the [authenticators](https://auth0.com/blog/not-all-mfa-is-created-equal/#Factors--Authenticators--and-Assurance) to confirm the user's identity and create highly secure public-private key credentials. There are two types of authenticators: roaming authenticators, like hardware security keys, and platform authenticators, like your laptop or device, that support biometrics, such as fingerprint recognition, facial recognition, and voice recognition, depending on the capabilities of the user's device.

### Seamless user experience

With WebAuthn, users can authenticate with a single gesture or action, providing a convenient and frictionless login experience. While delivering a seamless and convenient authentication experience for users, it also enhances security.

## WebAuthn Roles

**Relying Party** - This is the website or online service the user wants to access. The relying party initiates the WebAuthn authentication process and verifies the user's identity.

**WebAuthn Client Device** -  The user's device (e.g., smartphone, computer) that supports WebAuthn and communicates with the relying party. It is capable of hosting the private keypair in secret storage that a user can access through biometrics or PIN.

**User** -  The individual attempting to access a relying party's website or services.

**Authenticator** - There are two types of authenticators, i.e., Platform Authenticators and Roaming Authenticators. 
  
Platform Authenticators refer to a specific type of authenticator built into the user's device or platform, such as a smartphone, laptop, or desktop computer. For example, a smartphone's fingerprint sensor or a laptop's built-in biometric recognition system can act as a platform authenticator. 
  
Roaming Authenticators are authenticators not tied to any particular platform but can be used to authenticate across multiple devices. They are also sometimes referred to as cross-platform or external authenticators. e.g., hardware security keys like the YubiKey.

<include src="WebAuthnMeCTA" group="A"/>

## How WebAuthn Works

WebAuthn's mode of authentication consists of a Registration Flow and an Authentication Flow. With WebAuthn, there are no longer shared credentials between the user and the relying party. A public-private key pair is generated with the help of the authenticators and is used instead of the password. Let us look into the user journey of the registration and authentication flows.

### Registration flow

#### A User visits a website

The process begins when a user visits a website or a web application that supports WebAuthn for authentication and requests the website to create a new account.

#### Initiating registration

The website, often called the relying party, begins the registration process. It generates a unique and cryptographically random challenge and communicates to the user's browser that it wants to register a new public-private key pair for the user.

#### The User chooses an authenticator to generate a public-private key pair

The user selects their preferred authenticator, a platform authenticator (built into their device, e.g., fingerprint sensor), or an external authenticator (e.g., a hardware security key). The chosen authenticator generates a new public-private key pair for the user and signs the challenge generated by the relying party with those keys. 

#### The Authenticator sends back the user credentials

The private key is securely stored within the authenticator, while the public key is sent back to the website along with the signed challenge and an optional private key ID.

#### The Website stores the user credential

The website stores the user's public key and the private key ID (if sent) and associates it with the user's account for future authentication; 

![WebAuthn Registration Flow](https://images.ctfassets.net/23aumh6u8s0i/6tOAUn8BVSqRrvnoe9fekn/d4614b12e493faeefc6d3cfaf36f3245/WebAuthn_Registration_Flow.png) 

The registration process is completed, and no more shared secrets are exchanged over the network between the user and the server, eventually reducing the risk of stolen credentials.

### Authentication flow

Once the user's registration is complete, the returning user can verify the credentials and log in to the application. Following are the steps that take place in the authentication flow for the user.

#### User returns to the website 
When users return to the website to access the protected resources, the web application prompts the user to authenticate. The user provides the username to the server.

#### Website generates an authentication challenge
The website generates a new challenge and sends it to the user's browser.

#### User requests authenticator to sign the challenge
The user selects the authenticator they used during registration, or the authenticator may be automatically detected and requested to sign the challenge. 

#### Authenticator signs the challenge
The authenticator signs the challenge using the private key stored during the registration flow. The authenticator sends the signed response and the public key back to the website.

#### User verification
The website receives the signed response and the user's public key. It verifies the response by checking the signature against the stored public key. If the verification is successful, the website grants the user access to the requested resources.

![Authentication Flow](https://images.ctfassets.net/23aumh6u8s0i/5gbfSpwf2b3EOAP4gP1elm/ae3db34de58eca086f963d06303c54cb/WebAuthn_Authentication_Flow.png)

The user is authenticated securely without a password and with less friction to the user.

## How to Implement the WebAuthn API

Two methods in the WebAuthn API mediate between the user and the server to create the public-private key pair.

1. `navigator.credentials.create`
2. `navigator.credentials.get`

### Using the "navigator.credentials.create" method

The `navigator.credentials.create` method is used to initiate registering a new credential for a user. This method allows users to create a new credential, such as a public-private key pair, which can be used for secure authentication in the future. Here's how you can use `navigator.credentials.create`.

#### Prepare credential creation options
You need to define the options for the credential creation request. These options specify various credential creation parameters, such as the relying party ID (your website's domain), user information, and allowed authenticator types (e.g., platform authenticator or external security key).

Here's an example of how to create credential creation options:

```
const publicKey = {
  challenge: new Uint8Array(/* Generate a random challenge */),
  rp: {
    name: 'Webauthn Me', // Relying party name
    id: 'webauthn.me',     // Relying on party ID
  },
  user: {
    id: new Uint8Array(/* Generate a unique user ID */),
    name: 'jane.doe@example.com',
    displayName: 'Jane Doe',
  },
  pubKeyCredParams: [
    { type: 'public-key', alg: -7 }, // ES256 algorithm
  ],
  timeout: 60000, // 1-minute timeout
  attestation: 'direct', // Attestation type
};

```

The following section describes each variable in detail.

- `challenge`: A challenge is a random value generated by the server and included in the registration request that helps to prevent replay attacks. The challenge serves as a nonce (number used once), ensuring that each registration request is fresh and not subject to replay. It prevents attackers from intercepting and reusing a valid registration message to gain unauthorized access. The server should validate the response promptly and reject it if the challenge has expired or does not match.
- `rp`: The relying party is the entity that relies on WebAuthn for authentication. For example, it is the domain of the website that implements WebAuthn to enable secure user authentication. Validating the relying party information helps prevent phishing attacks.
- `user`: Information about the user who wants to register.
- `pubKeyCredParams`: It is an array that specifies the acceptable public key algorithms and parameters for the generated credential. The array consists of two properties,
    1. `type`: A string indicating the cryptographic algorithm to be used. Common values include "public-key" for ECDSA (Elliptic Curve Digital Signature Algorithm) or "rsa" for RSA (Rivest–Shamir–Adleman)
    2. `alg`: An integer representing the specific algorithm within the given type. For example,`-7`representing ES256 for ECDSA with SHA-256.
- `timeout`: The time limit for the credential creation process.
- `attestation`: The attestation parameter specifies how the authenticator (e.g., security key, biometric device) should attest to the authenticity of the public key credential it generates during the registration process. The attestation parameter can take different values, each representing a different attestation type. Common values include:
    1. `none`: No attestation is requested. The authenticator generates a credential without any assertion of its authenticity. This is suitable for scenarios where the relying party already has a secure means of verifying the authenticator.
    2. `direct`: The authenticator provides an attestation statement, but the format and content depend on the authenticator type. This is also known as "self-attestation."
    3. `indirect`: The authenticator forwards an attestation statement obtained from a third-party service, typically the manufacturer or a trusted party.

#### Call "navigator.credentials.create"
Use the `navigator.credentials.create` method to initiate the credential creation process.

```
navigator.credentials.create({ publicKey })
  .then((credential) => {
    // Handle the successful credential creation
    // Send the credential information to your server for storage
  })
  .catch((error) => {
    // Handle any errors that occurred during credential creation
  });

```
`publicKey`:  It is the variable defined in the previous step. 

#### Handle the Credential Creation Response
If the user successfully creates a credential, the `navigator.credentials.create` promise will resolve with a credential object. You should send this credential object to your server for storage and associate it with the user's account.

```
// Handle the successful credential creation
// Send the credential information to your server for storage
navigator.credentials.create({ publicKey })
  .then((credential) => {
    // Response object has information about the authenticator data, 
    // public key, transport mechanisms, and more.
    const response = credential.response;

    // Access attestationObject ArrayBuffer
    const attestationObj = response.attestationObject;

    // Access client JSON
    const clientJSON = response.clientDataJSON;

    // Return authenticator data ArrayBuffer
    const authenticatorData = response.getAuthenticatorData();

    // Return public key ArrayBuffer
    const pk = response.getPublicKey();

    // Return public key algorithm identifier
    const pkAlgo = response.getPublicKeyAlgorithm();

    // Return permissible transports array
    const transports = response.getTransports();
    
    // Send the credential information to the server for storage
    return credential;
  })
  .catch((error) => {
    // Handle any errors that occurred during credential creation
    console.log('FAIL', error)
  });


```

If the credential creation fails or if there are errors, the promise will be rejected, and you can handle the errors accordingly.

Remember that the server-side storage and management of user credentials are essential for the WebAuthn authentication process. The server should securely store the user's public key and other relevant information to enable future authentication.

### Using the "navigator.credentials.get" method

The `navigator.credentials.get` method is part of the WebAuthn API and is used to initiate the process of authenticating a user based on the credentials they have previously registered. This method is typically used in conjunction with the `navigator.credentials.create` method for credential registration. Here's how you can use this method.

#### Prepare authentication options
You need to define the options for the authentication request. These options specify the criteria for the user's credentials for authentication. You can include the relying party ID (e.g., your website's domain) and specify the allowed authentication methods.

Here's an example of how to create authentication options:

```
const publicKey = {
  challenge: new Uint8Array(/* Generate a random challenge */),
  rpId: 'webauthn.me', // Relying party ID
  allowCredentials: [
    {
      type: 'public-key',
      id: /* The credential ID of the user's registered credential */,
    },
  ],
  userVerification: 'preferred', // or 'required'
};
```

The following section describes each variable in detail.

- `userVerification:` It specifies the preferred user verification method that the relying party wishes to be performed during the WebAuthn authentication process. The [userVerification parameter](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/User_Presence_vs_User_Verification.html) can take different values, each representing a different user verification method. Common values include `required`, `preferred`, and `discouraged.`
- `allowCredentials:` It is an array that contains one or more "PublicKeyCredential" objects representing the credentials that the relying party is willing to accept during the authentication process. Each element in the allowCredentials array is an object with the following properties: 
  1. `type`: A string specifying the type of the credential. Commonly, this is set to "public-key".
  2. `id`: A byte array representing the credential ID. This corresponds to a credential that was previously created during the registration process.
- `challenge` and  `rpId` are the same parameters used for the `navigator.credentials.create` method.

#### Call "navigator.credentials.get"

Use the `navigator.credentials.get` method to initiate the authentication process:

```
navigator.credentials.get({ publicKey })
  .then((assertion) => {
    // Handle the successful authentication assertion
  })
  .catch((error) => {
    // Handle any errors that occurred during authentication
  });
```

`publicKey`:  It is the variable defined in the previous step.

#### Handle the authentication response
If the user successfully authenticates, the `navigator.credentials.get` promise will resolve with an authentication assertion containing information about the user's successful authentication. You can then send this assertion to your server for verification.

```
// Handle the successful authentication assertion
// Send the assertion to your server for verification
navigator.credentials.get({ publicKey })
  .then((assertion) => {
    // Handle the successful authentication assertion
    // The assertion response has information about the authenticator data, 
    // signature, and user handle
     const response = assertion.response;

    // Access authenticator data ArrayBuffer
    const authenticatorData = response.authenticatorData;

    // Access client JSON
    const clientJSON = response.clientDataJSON;

    // Access signature ArrayBuffer
    const signature = response.signature;

    // Access userHandle ArrayBuffer
    const userHandle = response.userHandle;

    return assertion;
  }).catch((error) => {
    // Handle any errors that occurred during authentication
    console.log('FAIL', error)
  });
```

If the authentication fails or if there are errors, the promise will be rejected, and you can handle the errors accordingly.

Remember that the server-side verification of the authentication assertion is an essential part of the process. The server should validate the assertion's signature and ensure that it matches a previously registered credential for the user.

These steps provide a high-level overview of how to use `navigator.credentials.create` and `navigator.credentials.get` in the WebAuthn API for user authentication. The actual implementation will vary based on your specific use case and server-side verification requirements.

## Conclusion

WebAuthn offers a passwordless and highly secure alternative to traditional authentication methods. Leveraging public key cryptography, user verification methods like biometrics, and a challenge-response model, WebAuthn effectively mitigates the risks associated with phishing attacks and enhances online security. It's important to note that while WebAuthn is phishing-resistant, it is not immune to all types of attacks. Therefore, proper implementation and security best practices on both the client and server sides are crucial to harness the security benefits of WebAuthn fully. [Auth0 supports WebAuthn](https://auth0.com/blog/mfa-with-webauthn-for-fido-device-biometrics-now-available/) and adheres to industry best practices and security standards, removing the heavy lifting of implementing on your own. It is a simple toggle switch in the configuration to show up in your login box, and all the background processing is taken care of by Auth0.

<include src="SignupCTA" text="Try out WebAuthn with Auth0?" linkText="Get started →" />

WebAuthn - A Short Introduction

arthur-bellore

I’m a tech content creator. I enjoy breaking up seemingly complicated topics into easy-to-understand pieces for people to read. When I’m not in front of a computer, you’ll usually find me reading books.

Cybersec Writer

Arthur Bellore

Transport Layer Security (TLS) is the cryptographic protocol behind pretty much any computer network used today: from web browsing to email, APIs, and VoIP. But how exactly does it work?

## SSL vs. TLS

SSL, or Secure Sockets Layer, is the predecessor to TLS. It was a cryptographic protocol developed by Netscape in 1994, but since it had serious flaws, it was never released to the public. SSL 2.0 was released publicly one year later, in 1995, but it, too, was found to have serious flaws. Finally, SSL 3.0 was rebuilt from the ground up and released in 1996.

Microsoft, who had its own version of the protocol, and Netscape agreed to hand over the project to the Internet Engineering Task Force (IETF) and make it an open standard. As part of the deal, the name was changed to TLS, Transport Layer Security, to signify that it no longer had ties with Netscape.

The first upgrade to SSL 3.0 was published in 1999 in [RFC 2246](https://datatracker.ietf.org/doc/html/rfc2246) as TLS 1.0. Tim Dierks, the editor of RFC 2246, has said [in his blog](https://tim.dierks.org/2014/05/security-standards-and-name-changes-in.html) that TLS 1.0 was really SSL 3.1, but they changed the name “so it wouldn’t look the IETF was just rubberstamping Netscape’s protocol.” Indeed, if you look at RFC 2246, it says:

This document describes TLS Version 1.0, which uses version { 3, 1 }. Version value 3.1 is historical: TLS version 1.0 is a minor modification to the SSL 3.0 protocol, which bears the version value 3.0.

TLS became the standard of encryption and authentication over computer networks, and it’s still being used today. The most recent version of the protocol is TLS 1.3, which was released in August 2018.

### What is the difference between SSL and TLS?

SSL hasn’t been updated since its release in 1996, and it was deprecated in 2015 in [RFC 7568](https://datatracker.ietf.org/doc/html/rfc7568). Most [modern browsers disable it by default](https://en.wikipedia.org/wiki/Version_history_for_TLS/SSL_support_in_web_browsers) or don’t support it outright anymore.

Despite this, because of the association between the two, many people still use the term SSL when they really mean to say TLS. Vendors typically use the same terms their target customers use to facilitate messaging, so their marketing collateral generally contains terms such as “SSL/TLS” or “SSL,” even though SSL is deprecated.

We now know that SSL and TLS are different things, but for the remainder of this article, SSL will be used interchangeably with TLS to match its everyday usage.

## Why SSL/TLS Was Created

For two computers to communicate with each other, they must perform a set of agreed-upon operations in a specific order. A **protocol** is what dictates those operations. The HTTP protocol is the protocol that web servers and clients use to establish a connection and communicate with each other through the Internet.

It works roughly as follows:

1. The server listens for new connections on port 80
2. The client connects to the server, and this starts a chain of operations as set forth by the HTTP protocol
3. The client sends a GET request to the server; the server receives the request, processes it, then sends back a response: headers and index.html, plus other content it might need to serve (CSS files, JavaScript files, cookies, etc.) for the client to render the content correctly.

This works to distribute content between two remote computers, but there is a problem: HTTP was intended to expand the local knowledge management tools throughout the multiple computers at CERN in the late 1980s, so it was designed as a clear text protocol.

Because it’s clear text, a malicious actor could insert themselves between client and server and potentially read sensitive information, such as credit card numbers or passwords, or they could intercept the client’s requests and serve back malicious files pretending to be server.

As the Internet evolved and the number of sensitive information flying around increased exponentially, an encryption layer sitting below HTTP was necessary. However, this is a bit tricky: if a bad actor can “listen in” the conversation between client and server while the connection is unencrypted, how can they exchange encryption keys securely?

One option would be for the two parties to create a public-private key pair and send over the public key pair to the other party, so they can use that to encrypt their packet before sending them over the wire.

The problem with this is that asymmetric (public-key) cryptography is _much slower_ than symmetric cryptography.

The "strength" of asymmetrical cryptography relies on modular arithmetic, mathematical operations that are very hard to do in the opposite direction. The numbers used in these operations need to be big enough to provide the necessary security, but performing arithmetic with very large numbers can be taxing on a CPU.

Symmetric cryptography, on the other hand, works differently and does not suffer from this problem. On top of that, most devices have AES instruction sets integrated into their CPUs to speed up AES operations, making AES encryption have almost zero overhead on modern devices.

The TLS protocol gets around this issue by using asymmetric cryptography to exchange keys at the beginning and then switch to symmetric keys (“sessions keys”) from then on in a process known as the TLS handshake.


## TLS handshakes

The exact steps of the TLS handshake will depend on which TLS version is supported by the client and server, as well as which parameters they are set to use.

Since most modern browsers still support TLS 1.2 and a lot of websites still use TLS 1.2 (according to a [paper published by Syed-Winkler](https://www.grin.com/document/1037281), as of February 2021, TLS 1.3 is supported by 42.9% of surveyed websites, while TLS 1.2 is supported by 99.3%), we will talk about TLS 1.2 first and then discuss how TLS 1.3 differs from 1.2.


### The TLS 1.2 handshake

TLS 1.2 can be configured to use many key exchange algorithms, and among them, the most well-known and widely used is the RSA key exchange algorithm. Let’s go over how the RSA algorithm works in TLS 1.2, then talk about how the process differs in TLS 1.3 with the [Diffie-Hellman](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) (DH) key exchange algorithm.

The RSA key exchange works roughly as follows in TLS 1.2:

1. **Server listens for new connections on port 443.**
2. **Client connects to port 443 and initiates the handshake process with a ClientHello message to the server.** This message contains the TLS versions and cipher suites the client supports and a 32-byte random number known as Client Random.
3. **Server says “hello” back with a ServerHello message.** The server selects a cipher and the TLS version from the list provided by the client, then generates a different 32-byte random number known as Server Random and sends it all back along with the server’s own SSL certificate.
4. **Client uses the SSL certificate to verify the server’s identity.** SSL certificates contain a public key generated by the server and a digital signature signed with the private key of a trusted third party known as a certificate authority (CA). Most web browsers and operating systems come bundled with public keys from trusted CAs, which are used to verify that the CA issued the certificate.
5. **The client verifies the server has the matching private key to the certificate through ClientKeyExchange.** The client generates the pre-master secret (a 48-byte random number) and encrypts it with the server’s public key obtained from the certificate. If the server is the true owner of the certificate, it must be able to decrypt the message and obtain the original pre-master secret.
6. **Server decrypts the pre-master secret.** Now both the server and client have the pre-master secret, the Server Random, and the Client Random. They can use that to derive the master secret using the previously agreed cipher and arrive at the same (symmetric) key, which will become the session key once both parties verify their keys match.
7. **Client sends a ChangeCipherSpec message.** This indicates that the client is ready to create the session key and start communicating through an encrypted tunnel using that key.
8. **Client proves to server it has the correct keys.** The client hashes all handshake records up to that point, encrypts them with the session key, and sends them to the server. If the server generates the correct key, it will be able to decrypt that message and verify the record hashes (which the server can independently generate).
9. **Server proves to the client that it has the correct keys.** The server does the same thing and sends it to the client.
10. **A secure connection is established.** If both keys match, the TLS handshake is complete.

<br>
#### Problems with TLS 1.2

TLS 1.2 left a lot of its configuration parameters up to the users, which often resulted in bad choices (the old security adage of “among too many options, the worst one will be chosen”).

Additionally, in the name of backward compatibility, TLS 1.2 also allowed old, insecure ciphers to be used. (TLS 1.2 itself was released in 2008.) As time passed, it became more prone to attacks as vulnerabilities in older cipher or versions of TLS were discovered.

On top of all that, the RSA key exchange has a few weaknesses:

* **The same public-private key pair is used both to authenticate the server and to encrypt the pre-master secret (item #5 above).** If an attacker obtains the private key, they will be able to re-generate the session keys and be to decrypt the entire session.
* **There is no Perfect Forward Secrecy (PFS).** Since the server’s private key doesn’t change, an attacker might record and store encrypted data for years, hoping to decrypt it years down the line if the server’s private key is ever leaked or compromised.
* **Performance.** It’s necessary to make two round trips between the client and server until the session key is established.

To address these problems, the IETF began developing TLS 1.3 in 2013 and finally released it to the public in August 2018.

### What changed in TLS 1.3

In practice, the main differences between TLS 1.3 and 1.2 are:

* Shorter handshake
* Only supports key exchange algorithms with perfect forward secrecy (PFS), such as ephemeral Diffie-Hellman
* Support for 0-RTT (Zero Round Trip Time) resumption

This represents a bit of a paradigm change in TLS 1.3: shifting the focus from user configurability and backward compatibility to security by being more opinionated.

This allowed the designers to create a shorter handshake (by restraining DH as the only key exchange algorithm) but also prevented developers from choosing insecure options by restricting the number of options available in the first place.

For example, while it was technically possible to use DH as the key exchange method in TLS 1.2, the participants were responsible for setting the DH parameters. Picking the right parameters is crucial to make sure the DH exchange is secure, as some parameters can be trivially broken.

In 2015, security researchers [published a paper](https://weakdh.org/) describing how the WeakDH attack, which affected 8.4% of the top 1 million domains at the time, could trick servers into using small (insecure) DH parameters, enabling adversaries to decrypt data transmitted between client and server.

TLS 1.3 makes it impossible to use anything but a set of DH parameters that are believed to be secure.

### The TLS 1.3 handshake

Because there are significantly fewer options for the client and server to agree on, the TLS 1.3 handshake is much simpler:

1. **Server listens for new connections on port 443.**
2. **Client connects to port 443 and initiates the handshake process with a ClientHello message to the server.** Since the list of cipher suites was vastly reduced in TLS 1.3 (from 37 to 5), the client assumes the server is going to use one of the five. It proactively calculates a key pair for each of the cipher suites and sends it to the server along with the protocol version.
3. **Server calculates the key session.** With the client’s key share, the server is able to generate the session key.
4. **Server says “hello” back with a ServerHello message.** The server generates its own key share and sends it over to the client, so it also can generate the session key, along with the server’s encrypted SSL certificate (using the session key created on #3).
5. **Client generates master secret and a secure connection is established.** The client receives the server’s key share and calculates the session key. It decrypts and verifies the server’s certificates, and if everything is good, the handshake is complete.

Note that there are two different public-private key pairs on an ephemeral DH exchange: the first is the ephemeral pair, created every time client and server establish a connection, which guarantees forward secrecy. The second pair, embedded on the SSL certificate, is used for authentication and doesn’t change.

Given that a new key is generated for every session, this feature guarantees PFS. If the encryption keys are compromised at a later date, the leaked key will only be able to decrypt the specific session to which it corresponds; all the prior sessions are still safe. As a result, large-scale storage of data transmitted between server and client is rendered worthless.

## How Auth0 Can Help

The temptation to intercept, undermine, and circumvent encryption has never been stronger. Cybercriminals are working to find ways to get around the issues that strong encryption presents due to the volume of valuable information that is sent between computers today.

While this rarely results in direct assaults against cryptographic algorithms or protocols, it frequently prompts attackers to devise novel methods of intercepting or capturing information. With these threats ever present, it is more crucial than ever to focus on maintaining strong and up-to-date implementations of effective encryption protocols.

Some applications are still running TLS versions older than 1.2, and others are still running the original SSL protocol. If yours is one of them, you should consider upgrading it immediately. Auth0 [supports both TLS 1.2 and TLS 1.3](https://auth0.com/docs/customize/custom-domains/self-managed-certificates/tls-ssl) and can help you keep your applications secure.

The TLS Handshake Explained

How to use the new user-jwts tool to test a protected ASP.NET Core Web API without involving an authorization server.

Test Authorization in ASP.NET Core Web APIs With the user-jwts Tool

pablo-cibraro

Pablo is an internationally recognized expert and entrepreneur with more than 22 years of experience in designing and implementing large distributed systems with Microsoft technologies and a Connected System MVP. <br>
For the last few years, Pablo has helped numerous Microsoft teams develop tools and frameworks for building service-oriented and web applications with .NET. <br>
Pablo now focuses on technologies that enable developers to build large-scale systems and web applications on the cloud, such as HTML5, Node.js, ASP.NET, Windows Azure and Amazon AWS.

Agilesight Cofounder

Pablo Cibraro

Learn about the new ASP.NET minimal Web APIs introduced in .NET 6.0 and how to secure them with Auth0.

Securing ASP.NET Minimal Web APIs with Auth0

vincenzo-chianese

Vincenzo Chianese is an Italian Software Developer focused on Web APIs and User Interfaces. He has been working for the last years in API companies such as Apiary, Oracle, LunchBadger, Stoplight. Currently, he is working for Microsoft to help move Microsoft Graph forward and authored some open-source tools in the market (Prism, Express Gateway).

API Architect

Vincenzo Chianese

Build your first web API in the functional programming world of Clojure with this step-by-step guide

## Introduction

This article will walk you through building a web API using Pedestal, a Clojure web framework. [Pedestal](http://pedestal.io/) is focused on APIs first and exemplifies the very best possibilities of Clojure's functional paradigm.

You'll put together a basic project with the necessary dependencies and serve up some basic information about superheroes. In a later article, we'll also secure the API using a collection of best practices and Auth0!

## Requirements

For this tutorial, you won't need much out of the box. Be sure you've:

1. Installed the [JDK](https://www.oracle.com/java/technologies/downloads/). This tutorial was written with the latest and greatest version of Java.
2. If you're on windows, set JAVA_HOME as an environment variable.
3. Wondered why JAVA_HOME isn't set by the JDK installation in 2021
4. Installed [Clojure](https://clojure.org/guides/getting_started)

Open up your command-line interface and check that you're good to go:

```bash
clj --version
 
Clojure CLI version 1.10.3.967
```

## Setup a New Clojure Project

>If you're brand new to Clojure, check out ["Why Developers Should Look into Clojure"](https://auth0.com/blog/why-developers-should-look-into-clojure/) first.

Clojure's ecosystem provides several build and dependency management tools. While [Leiningen](https://leiningen.org) and [Boot](https://github.com/boot-clj/boot/) provide this functionality and have been around a while, the Clojure team has provided the solution we'll be using for this article  [tools.deps](https://clojure.org/guides/deps_and_cli).

Skipping Leiningen reduces the number of things we need to install. **tools.deps** is included with the Clojure CLI and satisfies all of the requirements for this article, so you should be set.

Like `package.json` for Node, `pom.xml` for Maven projects, and `requirements.txt` in Python, Clojure's CLI uses a single file to manage its dependencies. Create a root folder (`clojure-pedestal`) for your project on your system and, in it, create a file called `deps.edn`.

`deps.edn` contains dependencies (for different environments, like development or production), additional commands/scripts, and much more. We'll keep it simple for now - but do know that EDN stands for ["Extensible Data Notation"](https://github.com/edn-format/edn) and is used across the Clojure universe.

### Add dependencies

For your Web API, you'll need to install a couple of Pedestal packages. In addition, we'll include some defacto-standard libraries for [logging](http://www.slf4j.org/) and accessing [environment variables](https://github.com/weavejester/environ). 

There's no "install dependency" command available in the Clojure CLI. Instead, we'll itemize what we need within `deps.edn`. When we invoke the Clojure CLI, it'll look into the file and download artifacts from our maven registry. You declare dependencies in the main hash-map, under the `:deps` keyword. Here's what your `deps.edn` should look like:

```clojure
{:paths ["src"]
:deps {io.pedestal/pedestal.service {:mvn/version "0.5.9"}
       io.pedestal/pedestal.route {:mvn/version "0.5.9"}
       io.pedestal/pedestal.immutant {:mvn/version "0.5.9"}
       org.slf4j/slf4j-simple {:mvn/version "1.7.32"}
       environ/environ {:mvn/version "1.2.0"}}}
```

### Add core.clj

Within your project folder, create two folders in sequence: `src` and `app`. Within `app`, add `core.clj`. your directory should look like this:

```
clojure-pedestal
|   deps.edn
|___src
    |
    |___app
        core.clj
```

>Because of how the JVM constructs the classpath, it is important that the namespace and the path of the file match. For instance, if we have a namespace called `app.core.models.user`, the file will have to be `src/app/core/models/users.clj`.

## Pedestal Fundamentals

### Hello world

Let's walk through the fundamental steps to have an HTTP Web API listening for requests and returning data.

In `core.clj`, declare a namespace called `app.core` and require some of the dependencies we're using. Avoid spending time understanding what we're using each dependency for; it will be more apparent once we write some code.

```clojure
(ns app.core (:require [io.pedestal.http :as http]
                       [environ.core :refer [env]]))
```

To create a functioning server, you'll need to:

* Define the **handler** for a specific route
* Define the **routes** and attach them to handlers
* Create a **service map** containing some configuration options
* Create a **server instance** and then run it

This is what some basic code to accomplish those goals should look like:

```clojure
(defn hello-world [_] {:status 200 :body "Hello"}) ; Route handler
 
(def service-map {::http/routes #{["/" :get hello-world :route-name :hello-world]} ; Routes
             ::http/type   :immutant
             ::http/host   "0.0.0.0"
             ::http/join?  false
             ::http/port   (Integer. (or (env :port) 5000))}) ; Service map
 
(defn -main [_] (-> service-map http/create-server http/start)) ; Server Instance

```

That's it! With just this code and our packages, we can now run the server and try it out. From your root directory, run:

```bash
clj -X app.core/-main
```

...and then you can use `curl` to test the Web API ...

```bash
curl http://localhost:5000
Hello
```

### Routing fundamentals

Next up is using Pedestal's intuitive routing features to return some data. We'll also filter and expand that data at different endpoints when necessary.

As you work through these instructions, start just under your namespace declaration.

Once again, in `core.clj`, define some static superhero data to play with:

```clojure
(def heroes [{:name "Clark" :surname "Kent"  :hero "Superman"}
             {:name "Bruce" :surname "Wayne"  :hero "Batman"}
             {:name "James" :surname "Logan"  :hero "Wolverine"}
             {:name "Steve" :surname "Rogers" :hero "Captain America"}
             {:name "Bruce" :surname "Banner" :hero "Hulk"}])
```

Then define two additional route functions besides your root "Hello World". They should:

1. Return all the superheroes we have defined
2. Return the hero matching the name provided as a route parameter
<br>

```clojure

(defn get-heroes [_] {:status 200 :body heroes})

(defn get-hero [{{:keys [hero]} :path-params
                {:keys [extended]} :query-params}]
 (if-let [hero (->> heroes
                    (filter #(= hero (:hero %)))
                    first)]
   {:status 200 :body (if extended hero (dissoc hero :hero))}
   {:status 404}))

```

Be sure to update your route map accordingly. While we're here, extract your routes to live outside of the API specification. That will keep our functions and definitions short:

```clojure

(def routes #{["/" :get hello-world :route-name :hello-world] ;Routes
              ["/heroes/:hero" :get get-hero :route-name :get-hero]
              ["/heroes" :get get-heroes :route-name :get-heroes]})

(def service-map
  {::http/routes routes
   ::http/type :immutant
   ::http/host "0.0.0.0"
   ::http/join? false
   ::http/port (Integer. (or (env :port) 5000))}) ; Service map

```

While Pedestal does a lot for us and the code above is simple, it's worth dissecting it to explain some of the Clojure features that keep code concise.

Each route in Pedestal is technically a specialized [Interceptor](http://pedestal.io/guides/what-is-an-interceptor). Interceptors are a common web framework concept used in things like Angular as well as Pedestal. Simply put, they let you layer functions to create a "pipeline" to handle web requests. We will return to the concept of interceptors later.

Pedestal routes take a [request map](http://pedestal.io/reference/request-map) and return a [response map](http://pedestal.io/reference/response-map) with the response details. 

```clojure
(defn hello-world [request] {:status 200 :body "Hello"})
```

The request map contains query parameters under the `:query-params` key and path parameters under the `path-params` key. Typically, to get the data we need from a map, we need to access them by keys. Here's what that would look like in our hello-world method, attached to our root route:

```clojure
(defn hello-world [request]
 (let [query-params (:query-params request)
       path-params (:path-params request)]) {:status 200 :body "Hello"})
```

From there, you could access the specified parameter with either a threading macro or using `get-in`...

```clojure
(defn hello-world [request]
 (let [extend (get-in request [:query-params :extended] )
       path-params (get-in request [:path-params :hero])]) {:status 200 :body "Hello"})
```

This method is legit — but it's a little wordy. To fix that, Clojure supports destructuring in binding statements. Destructuring is syntactic sugar that saves lines of code when accessing maps or sequential data structures.

Consider a nested map like this one:

```clojure
(def locations {:type "Office" :address {:street "Ocean Drive" :zip 90210 :city "Beverly Hills" }})
```

It is possible to destructure the map and access particular keys in several ways:

```clojure
; Destructuring in a let statement
(let [{:keys office} locations] (println office))
 
; Destructuring in a function
(defn print-office [{:keys office}] (println office))
 
; It also works in nested maps
(let [{{:keys [city]} :address} locations] (println city))
 
; Destructuring Sequential structures, like our superhero data
(defn simple-heroes  ["Clark" "Kent" "Superman"])
(let [[name surname hero]] (println name " - " surname " - " hero))
```

Destructuring has a lot of facets we cannot explore here, but the [official documentation](https://clojure.org/guides/destructuring) contains a detailed guide on how best to use this feature. However, with this crash course, we should now understand what's happening at the beginning of our function `get-hero`:

```clojure
(defn get-hero [{{:keys [hero]} :path-params
                {:keys [extended]} :query-params}] {})

(defn get-hero [{{:keys [hero]} :path-params
                {:keys [extended]} :query-params}]
                ;...
```

...which can be interpreted as saying: "From path params extract the hero key; from query, params extract the extended key."

In case you're thinking: "hey, that looks a bit like SQL query expressed as data structure" (I'm psychic) — you're onto something. Indeed, [Datalog](https://www.learndatalogtoday.org) is a query language that expresses queries as data. It's used by [Datomic](https://www.datomic.com), which we will explore in a future article.

As a counter-example where destructuring _might_ not make sense, take a look at the filter statement we are using to find the hero by name in `get-hero`:

```clojure
(filter #(= h (:hero %)))
```

With destructuring, you need to "fall back" to a regular fn definition instead of a "lambda". That means the code would look like this:

```clojure
(filter (fn [{:keys hero}] (= h hero)))
```

To destructure, we need to "fall back" to a regular fn definition instead of a "lambda". There's not a dramatic improvement in readability, so I suggest accessing the key explicitly.

### Serving Data

After applying the modifications above, our code should look like this:

```clojure
(ns app.core (:require [io.pedestal.http :as http]
                       [environ.core :refer [env]]))

(def heroes [{:name "Clark" :surname "Kent" :hero "Superman"}
             {:name "Bruce" :surname "Wayne" :hero "Batman"}
             {:name "James" :surname "Logan" :hero "Wolverine"}
             {:name "Steve" :surname "Rogers" :hero "Captain America"}
             {:name "Bruce" :surname "Banner" :hero "Hulk"}])

(defn hello-world [request]
  (let [extend (get-in request [:query-params :extended])
        path-params (get-in request [:path-params :hero])]) {})

(defn get-hero [{{:keys [hero]} :path-params
                 {:keys [extended]} :query-params}]
  (if-let [hero (->> heroes
                     (filter #(= hero (:hero %)))
                     first)]
    {:status 200 :body (if extended hero (dissoc hero :hero))}
    {:status 404}))

(defn get-heroes [_] {:status 200 :body heroes})

(def routes #{["/" :get hello-world :route-name :hello-world]
              ["/heroes/:hero" :get get-hero :route-name :get-hero]
              ["/heroes" :get get-heroes :route-name :get-heroes]})

(def service-map
  {::http/routes routes
   ::http/type :immutant
   ::http/host "0.0.0.0"
   ::http/join? false
   ::http/port (Integer. (or (env :port) 5000))}) ; Service map

(defn -main [_] (-> service-map http/create-server http/start)) ; Server Instance
```

If we start the server again now and try to get some data, we should now be able to get results and test out our new endpoints:

```bash
curl http://localhost:5000/heroes
[{:name "Clark", :surname "Kent", :hero "Superman"} {:name "Bruce", :surname "Wayne", :hero "Batman"} {:name "James", :surname "Logan", :hero "Wolverine"} {:name "Steve", :surname "Rogers", :hero "Captain America"} {:name "Bruce", :surname "Banner", :hero "Hulk"}]
 
curl http://localhost:5000/heroes/Superman
{:name "Clark", :surname "Kent"}
 
curl "http://localhost:5000/heroes/Superman?extended=1"
{:name "Clark", :surname "Kent", :hero "Superman"}
```

You can indeed see the API is behaving as you'd expect. However, this response isn't JSON - which you can see from the syntax or by looking at the response details via `curl -v`:

```bash
$ curl localhost:5000/heroes/Superman -v
...
> Content-Type: application/edn
```

[EDN](https://github.com/edn-format/edn) is arguably a better format than JSON for several reasons, especially if you're using  [ClojureScript](https://clojurescript.org).  However, the lingua franca of publicly exposed APIs and JavaScript applications is JSON. For this reason, you're going to modify our application to return data in JSON by default. 

To do so, you need to modify our Service Map (where we specify our options) and add a new interceptor that will serialize the body to be JSON whenever it makes sense. The good news is that Pedestal provides an interceptor out of the box we can use.

Our code's `http/create-server` function will look for the `::http/interceptors` key in the service map. If it does not exist there, it will automatically use some [default interceptors](http://pedestal.io/reference/default-interceptors) that perform a series of common tasks. Since we need to add a new interceptor, we're going to need to update the interceptor chain by hand:

```clojure
(def service-map (-> {::http/routes routes
                     ::http/type   :immutant
                     ::http/host   "0.0.0.0"
                     ::http/join?  false
                     ::http/port   (Integer. (or (env :port) 5000))}
                http/default-interceptors
                (update ::http/interceptors into [http/json-body])))
```

Here we:

- Define the `service` with the routes and other keys
- Pass the map to the `http/default-interceptors` function that will return a new service map with the `::http/interceptors` key
- Add the `json-body` interceptor to the chain to serialize the data as JSON when appropriate.

If we try to request the same data again using `curl` we can see now that the response is JSON encoded:

```bash
curl http://localhost:5000/heroes/Superman
{"name":"Clark","surname":"Kent"}
```

You could apply the exact same approach to incoming body parameters if you had a route that used them. I won't dive deeply here, but the installation method for the [body-params](https://github.com/pedestal/pedestal/blob/master/service/src/io/pedestal/http/body_params.clj#L178) interceptor is the same as other interceptors.

We've completed a significant milestone with us returning data in the format most people expect when interacting with a Web API! But we're not done. Any Web API worth its salt should be well protected. You'll use Auth0 and some custom interceptors to accomplish that in my next article.

Create an API server with Clojure and Pedestal

Learn more about how we can secure our Clojure Web API using Auth0

In my [previous article](https://auth0.com/blog/create-an-api-server-with-clojure-and-pedestal/), we built a simple Web API in Clojure with the Pedastal framework. We covered some core concepts essential to know for writing Clojure and serving data on the web.

It was a great start! But the very next thing we should consider when building a Web API is making sure that it's secured. 

## Requirements

Of course, you'll want the source code that we ended up with at the close of the previous article. You'll also need to sign up for a free Auth0 account. You won't need a credit card, and this will be the simplest way for us to add basic Authentication.
 
### Interceptors explained
 
We have already used Interceptors while building our application. From our previous article:

> Simply put, they let you layer functions to create a "pipeline" to handle web requests.

They can also be used for responses, as we've seen with our JSON serialization example above.
 
### Building a base interceptor
 
In Pedestal, an interceptor is nothing more than a map with a `:name` along with `:enter`,  `:leave`, and `:error` keys. The name is (you guessed it) the name, while the last three items represent optional keys that receive a [context map](http://pedestal.io/reference/context-map) as an argument. Each of these keys is executed when the request is coming in when the response is being sent, and if an error happens along the way. You'll need to include at least one of these functions for this to count as an interceptor!
 
For instance, let's say we want to create an interceptor that inserts a specific response header for every response we send. To accomplish this, all we need to do is create a map with a function on the `:leave` keyword and associate the header:
 
```clojure
(def header-interceptor {
 :name "header-interceptor"
 :leave (fn [ctx] (assoc-in ctx [:response :headers "AppName"] "Pedestal-Auth0-App"))})
```
 
Pedestal also offers helpers to write a specific type of interceptor without having to specify the entire map. Here's that same function using these helpers:
 
```clojure
(require 'io.pedestal.interceptors.helpers :as helpers)
 
(def header-interceptor (helpers/on-response (fn [response] (assoc-in response [:headers "AppName"] "Pedestal-Auth0-App"))))
```
 
Armed with a basic understanding of interceptors in Pedastal, we can now set up an Auth0 account and then write our interceptor to validate any tokens provided in a request.
 
## Validating a Token

In an OAuth-compliant application, Identity providers must provide information to validate JWT tokens that they issue. Many frameworks and languages create black boxes where you provide some configuration parameters, and they do the rest. We're going to go into a bit more detail in this application. Here are some basic concepts to understand:

### JSON Web Tokens
Most documentation sources and developers shorten JSON Web Tokens to just JWT. JWTs are essentially long strings that encode JSON, and are frequently used for Authentication and Authorization. Identity providers issue JWTs and include information relevant to the apps that use them, such as your name, email address, or permissions for that app. If you're unfamiliar with JWTs I highly suggest [Auth0's documentation](https://auth0.com/docs/security/tokens/json-web-tokens) on the matter. When issued by an Identity provider, they're often signed so that you can know they're authentic, which leads us to...

### JSON Web Key Set
JSON Web Key Set's acronym is JWKS. We'll use the acronym for the remainder of this article. This key set contains the *public* keys that say, "Yeah, I made that token." The Identity provider has used a separate and private cryptographic key to construct the token. This process that allows for a public verification key and a private construction key is called asymmetric encryption. 

We'll need to retrieve the location of the JSON Web Key set for our Identity provider when we create a new Application in the Auth0 portal so we can verify JWTs. You can read a bit more about the concept in the [Auth0 documentation](https://auth0.com/docs/security/tokens/json-web-tokens/json-web-key-sets). 

### Create a new Auth0 application

Before writing the code to validate a token issued by an identity provider effectively, let's quickly review a couple of steps necessary to set up Auth0.
 
Once we've logged in, select Applications -> APIs from the left menu and create a new API. For demo purposes, we can just put a random name and an identifier. In my case, I am going to be using `clojure-pedestal` for both.

![Creating a new API in Auth0](https://images.ctfassets.net/23aumh6u8s0i/3IGLaJE64V2cWe3X4tahSX/70f98430ee2beab09b258e52f6ad5006/clojure_04.png)

When confirming the operation, Auth0 will also create a default Test application for the new API. Click on Applications -> Applications on the left menu to review the application's details. From the **Settings** tab, we will need to grab the domain. This is the base URL we'll need to determine a JWKS location.

![The Application settings we'll need to configure in Clojure](https://images.ctfassets.net/23aumh6u8s0i/7qAlQDPvlD9qLqx4k2cznV/bb18a3cbaaef5e58d31524cd5d8eadf0/clojure_05.png)

In this example, since my domain is https://dev-q6rh8--8.us.auth0.com/, my JWKS URL will be https://dev-q6rh8--8.us.auth0.com/.well-known/jwks.json

### Set up the authorization interceptor in Pedestal
 
Auth0 offers several Java libraries to work with JWT and JWK. Since Clojure has a good interoperability story with Java, we can use these libraries to write our interceptor.
 
If you've been writing Clojure for a little bit this should be simple. We will take it easy for this article and use a third-party Clojure library that will do most of the work. If you're curious/eager to see what using the Auth0 Java libraries would look like, you can take a look at the reference implementation that accomplishes the same thing at the end of this article.
 
The first thing we're going to do is to add a library providing the helpers we need to decode and verify the JWT in `deps.edn`:
 
```diff
{:paths ["src"]
:deps {io.pedestal/pedestal.service {:mvn/version "0.5.9"}
       io.pedestal/pedestal.route {:mvn/version "0.5.9"}
       io.pedestal/pedestal.immutant {:mvn/version "0.5.9"}
       org.slf4j/slf4j-simple {:mvn/version "1.7.32"}
-        environ/environ {:mvn/version "1.2.0"}}}
+        environ/environ {:mvn/version "1.2.0"}
+        no.nsd/clj-jwt {:git/url "https://gitlab.nsd.no/clojure/clj-jwt.git" :git/sha "bc23acb3c7cbf0d2def2d395c3e3d9c405be28d5"}}}
```
 
We can see that the `clj-jwt` has been imported from the repository directly instead of the Maven Central registry. This is a legitimate use case, and it works out of the box with `tools.deps`.

Let's now create a new file `src/app/jwt.clj`, and use the following code:
 
```clojure
(ns app.jwt (:require [no.nsd.clj-jwt :as clj-jwt]
                      [io.pedestal.interceptor.helpers :as interceptor]))
 
(defn- unauthorized [text]
 {:status  401
  :headers {}
  :body    text}) ; Helper to return a 401 status code
 
(defn decode-jwt [{:keys [required? jwk-endpoint]}]
 (interceptor/before
  ::decode-jwt
  (fn [ctx] (if-let [auth-header (get-in ctx [:request :headers "authorization"])]
              (try (->> auth-header
                        (clj-jwt/unsign jwk-endpoint)
                        (assoc-in ctx [:request :claims]))
 
                   (catch Exception _
                     (assoc ctx :response (unauthorized "The token provided is not valid"))))
 
              (if required? (assoc ctx :response (unauthorized "Token not provided"))
                  (assoc-in ctx [:request :claims] {}))))))
```
 
We can now import and apply our interceptor in our web application by updating core.clj:
 
```clojure
(ns app.core (:require [io.pedestal.http :as http]
                       [io.pedestal.interceptor.helpers :as helpers]
                       [app.jwt :refer [decode-jwt]] ;Add the reference to the new class
                       [environ.core :refer [env]]))
                       
...

(def jwk-endpoint "https://application-name.us.auth0.com/.well-known/jwks.json")
 
(def service-map (-> {::http/routes routes
                     ::http/type   :immutant
                     ::http/host   "0.0.0.0"
                     ::http/join?  false
                     ::http/port   (Integer. (or (env :port) 5000))}
                http/default-interceptors
                (update ::http/interceptors into [http/json-body
                                                  (decode-jwt {:required? true
                                                               :jwk-endpoint jwk-endpoint})])))
 
```
 
And now we can try to send some requests. To obtain a valid JWT token, we would theoretically have to complete an oAuth2 flow. For testing purposes, Auth0's UI offers a token for your current username that you can grab directly from the "Test" tab of the API:

![Getting test information from the Auth0 Portal](https://images.ctfassets.net/23aumh6u8s0i/5JO6ewpLrkkRItejcsrevD/af2f21dd6118f8d561f9f1255943ae31/clojure_06.png)

Now, let's send three requests to our API:

1. One with that JWT added correctly to the headers
2. One with an invalid JWT added to the headers
3. One with no JWT or additional headers at all

The first should be successful, with the remainder being rebuffed with a 401 HTTP status code by our new interceptor.
 
```bash
curl http://localhost:5000/ --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikhsb2NuQ1ZiRFRzdjVMTEs5d2RpeiJ9.eyJpc3MiOiJodHRwczovL3ZuY3oudXMuYXV0aDAuY29tLyIsInN1YiI6IldJeVUybTdZY3BWMHlCeU52dVNHSGpWUEEzYXFRbnA5QGNsaWVudHMiLCJhdWQiOiIvZGV2L251bGwiLCJpYXQiOjE2MzE4Mjk3NTQsImV4cCI6MTYzMTkxNjE1NCwiYXpwIjoiV0l5VTJtN1ljcFYweUJ5TnZ1U0dIalZQQTNhcVFucDkiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.tvzoDnqE5GWfqUKl0XbFtJBv_E3704qDoMOb9YheRj-409ntIcLs02UKVbR1g28-fDEPcQ-IxGRTBcOPEYy7X0HB-IByPCDink_Kj-hJ5O_2ft9I_lYZFOmeRL7TqD3TF9S17hta5UAFEj9zxQ_c_gcI7VY0F3t7iMfe3pNu9ut1l9-iYqjJ_BNCf-pxfQpWqnfQCnjU1qStGHPRmaK1dzXFIdXnH8S0rixcsuaxt5sbFivCIuQTNZ8QxvsW-vJekW1T2IkFOlGRWWWUoKTW2j4PnFlMWnCm7O91xR0zEaAHdQkmAob323qJf9IgucGxD3emX1k_ugLHdfnpvELaEQ'
< HTTP/1.1 200 OK
 
curl http://localhost:5000/ --header 'authorization: Bearer thisIsInvalid'
< HTTP/1.1 401 Unauthorized
 
curl http://localhost:5000/
< HTTP/1.1 401 Unauthorized
```
 
Our interceptor is now checking out all the requests and ensuring a valid token is included before moving on.
 
To give more detail about how JWTs work, we can also create a new route to return the claims encoded in the token to the sender. Update core.clj again:
 
```clojure
…
…
(defn get-claims [req] {:status 200 :body (:claims req)}) ; Add a new route returning the claims on the request object
 
(def routes #{["/heroes/:hero" :get get-hero :route-name :get-hero]
             ["/heroes" :get get-heroes :route-name :get-heroes]
             ["/claims" :get get-claims :route-name :get-claims]
             ["/" :get hello-world :route-name :hello-world]})
```
 
```bash
curl http://localhost:5000/claims --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikhsb2NuQ1ZiRFRzdjVMTEs5d2RpeiJ9.eyJpc3MiOiJodHRwczovL3ZuY3oudXMuYXV0aDAuY29tLyIsInN1YiI6IldJeVUybTdZY3BWMHlCeU52dVNHSGpWUEEzYXFRbnA5QGNsaWVudHMiLCJhdWQiOiIvZGV2L251bGwiLCJpYXQiOjE2MzE4Mjk3NTQsImV4cCI6MTYzMTkxNjE1NCwiYXpwIjoiV0l5VTJtN1ljcFYweUJ5TnZ1U0dIalZQQTNhcVFucDkiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.tvzoDnqE5GWfqUKl0XbFtJBv_E3704qDoMOb9YheRj-409ntIcLs02UKVbR1g28-fDEPcQ-IxGRTBcOPEYy7X0HB-IByPCDink_Kj-hJ5O_2ft9I_lYZFOmeRL7TqD3TF9S17hta5UAFEj9zxQ_c_gcI7VY0F3t7iMfe3pNu9ut1l9-iYqjJ_BNCf-pxfQpWqnfQCnjU1qStGHPRmaK1dzXFIdXnH8S0rixcsuaxt5sbFivCIuQTNZ8QxvsW-vJekW1T2IkFOlGRWWWUoKTW2j4PnFlMWnCm7O91xR0zEaAHdQkmAob323qJf9IgucGxD3emX1k_ugLHdfnpvELaEQ' -v
< HTTP/1.1 200 OK
< Content-Type: application/json;charset=UTF-8
 
{"iss":"https://dev-q6rh8--8.us.auth0.com/","sub":"WIyU2m7YcpV0yByNvuSGHjVPA3aqQnp9@clients","aud":"clojure-pedestal","iat":1631829754,"exp":1631916154,"azp":"WIyU2m7YcpV0yByNvuSGHjVPA3aqQnp9","gty":"client-credentials"}
```
 
## Conclusions

Building your own Authentication handler isn't an everyday activity in modern web development. Many devs will go their entire career without having to configure JWKS URLs or decoding claims in a token - instead, they'll plug in a library with nice documentation and hope that it works. 

Clojure and Pedastal let you take a much better look under the hood at this essential process. Even better, the language and framework make this process incredibly easy to show in a tiny Web API project.

To get more information about Pedestal, its roadmap, and documentation, you can refer to the [official website](http://pedestal.io).

We'll try to see something more complicated in the next installment, such as database interactions with [Datomic](https://datomic.com)
 
### Using Auth0 Java Libraries
 
For reference, this is what implementing the same JWT decoder/verifier would look like using the official Auth0 SDK.
 
```clojure
(ns app.auth
 (:require [cheshire.core :as json]
           [io.pedestal.interceptor.helpers :as interceptor])
 (:import (java.net URL)
          (com.auth0.jwt JWT)
          (com.auth0.jwt.exceptions SignatureVerificationException AlgorithmMismatchException TokenExpiredException JWTVerificationException JWTDecodeException)
          (com.auth0.jwt.algorithms Algorithm)
          (com.auth0.jwk UrlJwkProvider)
          (com.auth0.jwt.interfaces RSAKeyProvider)
          (org.apache.commons.codec Charsets)
          (org.apache.commons.codec.binary Base64)))
 
(defn- new-jwk-provider
 [url]
 (-> (URL. url)
     UrlJwkProvider.))
 
(def ^{:private true} rsa-key-provider
 (memoize
  (fn [url]
    (let [jwk-provider (new-jwk-provider url)]
      (reify RSAKeyProvider
        (getPublicKeyById [_ key-id]
          (-> (.get jwk-provider key-id)
              (.getPublicKey)))
        (getPrivateKey [_] nil)
        (getPrivateKeyId [_] nil))))))
 
(defn- base64->map
 [base64-str]
 (-> base64-str
     Base64/decodeBase64
     (String. Charsets/UTF_8)
     json/parse-string))
 
(defn- decode-token
 [algorithm token {:keys [issuer leeway-seconds]}]
 (let [add-issuer #(if issuer
                     (.withIssuer % (into-array String [issuer]))
                     %)]
   (-> algorithm
       (JWT/require)
       (.acceptLeeway (or leeway-seconds 0))
       add-issuer
       .build
       (.verify token)
       .getPayload
       base64->map)))
 
(defn- decode [token {:keys [jwk-endpoint] :as opts}]
 (-> (Algorithm/RSA256 (rsa-key-provider jwk-endpoint))
     (decode-token token opts)))
 
(defn- find-token [{:keys [headers]}]
 (some->> headers
          (filter #(.equalsIgnoreCase "authorization" (key %)))
          first
          val
          (re-find #"(?i)^Bearer (.+)$")
          last))
 
(defn- unauthorized [text]
 {:status  401
  :headers {}
  :body    text})
 
(defn decode-jwt [{:keys [required?] :as opts}]
 (interceptor/before
  ::decode-jwt
  (fn [ctx]
    (try
      (if-let [token (find-token (:request ctx))]
        (->> (decode token opts)
             (assoc-in ctx [:request :claims]))
        (if required? (assoc ctx :response (unauthorized "Token not provided"))
            (assoc-in ctx [:request :claims] {})))
 
      (catch JWTDecodeException _
        (assoc ctx :response (unauthorized "The token provided is not valid")))
 
      (catch SignatureVerificationException _
        (assoc ctx :response (unauthorized "Signature could not be verified")))
 
      (catch AlgorithmMismatchException _
        (assoc ctx :response (unauthorized "Algorithm verification problem")))
 
      (catch TokenExpiredException _
        (assoc ctx :response (unauthorized "Token has expired")))
 
      (catch JWTVerificationException _
        (assoc ctx :response (unauthorized "Invalid claims")))))))
```


Secure a Clojure Web API with Auth0

What is the best way to apply Role-Based Access Control (RBAC) to your ASP.NET Web API? Let's find out together.

Role-Based Authorization for ASP.NET Web APIs

Learn how to build a CRUD Web API with ASP.NET through this practical tutorial.

Building ASP.NET CRUD Web APIs

Checking user permissions allows you to have more control over access to your ASP.NET Web API.

Protecting a Web API from unauthorized users is the first step to get control over who can access it. However, simply excluding anonymous users may be insufficient in some situations. You may need to control over who can do what on your application. This article will show you how to define and check permissions for users accessing your ASP.NET Web API secured with Auth0.

## The Need for Permissions

A previous article introduced [how to enable authorization for ASP.NET Web APIs](https://auth0.com/blog/aspnet-web-api-authorization/). The sample application accompanying that article is an ASP.NET Web API that implements the CRUD (*Create*, *Retrieve*, *Update*, *Delete*) operations over a glossary of terms. That article explains how to protect the Web API by using Auth0 so that only authorized users can create, modify, and delete glossary items. Everyone can still get the list of terms or a single glossary item.

That worked pretty well! However, you may need more granular control over the users who can do specific operations. For example, you may want to give some users the ability to add a new glossary term or modify an existing one, but you don't want them to delete items. Only specific users should be able also to delete items. To achieve this control level, you must deal with permissions.

In the security context, a **permission** is a property of a resource that indicates the operation a user can do on it, like, for example, read, write, print, send, etc. In the case of your sample application, you have the glossary and term resources. Regarding the former, you can get the list of terms and add new items. Regarding the latter, you can read, update, or delete it.

<details>
  <summary>Permissions vs. privileges</summary>
Usually, permissions and privileges are used interchangeably, but technically they have precise and different meanings in the context of computer security.


A **permission** is an action that can be performed on a resource. It is somehow bounded to the resource, and you can consider it as a resource property.

A **privilege** is a permission assigned to a user or an application. When you assign the writing permission to a user, you are granting them a privilege.
</details>

## Setting up the Web API Application

The goal of this article is to show you how to implement permission-based authorization in this sample application. 

> Make sure you have [the latest .NET SDK](https://dotnet.microsoft.com/download/dotnet/current) already installed on your machine to run the sample ASP.NET application.

So, let's start by downloading the source code with the following command:

```bash
git clone --branch add-authorization --single-branch https://github.com/auth0-blog/glossary-web-api-aspnet.git
```

Once you download the application, register it with Auth0 in order to enable support for the authorization service. If you haven't an Auth0 account, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one</a>. Follow the [instructions in this article to register the application with Auth0](https://auth0.com/blog/aspnet-web-api-authorization/#Registering-the-Web-API-with-Auth0).

After you completed the registration, move to the `glossary-web-api-aspnet` folder and open the `appsettings.json` configuration file. Its content looks as follows:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "Audience": "YOUR_UNIQUE_IDENTIFIER"
  }
}
```

Replace the `YOUR_AUTH0_DOMAIN` placeholder with your Auth0 domain and the `YOUR_UNIQUE_IDENTIFIER` placeholder with the value you provided as a unique identifier of your API (`https://glossary.com`, if you kept the value suggested in [the mentioned article](https://auth0.com/blog/aspnet-web-api-authorization/#Registering-the-Web-API-with-Auth0)).

> Note: Your Auth0 domain is a string in the form `YOUR-TENANT-NAME.auth0.com` where `YOUR-TENANT-NAME` is the name you provided when you created your account with Auth0. For more information, [check the documentation](https://auth0.com/docs/getting-started/the-basics#domains).

Now, launch the ASP.NET Web API application by typing `dotnet run` in a terminal window. By pointing your browser to `https://localhost:5001/swagger`, you should see the [Swagger UI](https://swagger.io/tools/swagger-ui/) shown below to test the API interactively:

![Protected Web APIs in Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/1rNBChKdbCr9fKdpbbYcKR/014f6ace0411febc726959cd88ed8e6a/protected-swagger-ui-webapi.png)

To call the `POST`, `PUT`, and `DELETE` actions, [you need an access token, as explained in this section](https://auth0.com/blog/aspnet-web-api-authorization/#Testing-the-Secure-Web-API).

Now you are ready to set up permissions on your Web API.

## Defining Permissions for an API

The first step is to define the permissions for your application. These permissions can vary depending on the needs of your application. In the glossary Web API application, we are going to define the permissions identified by the following strings:

- `create:term`. This permission allows you to add a new term to the glossary.
- `update:term`. With this permission, you can update an existing term.
- `delete:term`. This permission allows you to delete a term from the glossary.

To associate these permissions with your API, go to the [API section](https://manage.auth0.com/#/apis) of your Auth0 Dashboard and select the API you defined for the glossary application. Then select the *Permissions* tab. Here you can add the permissions with their descriptions as defined above. At the end of this process, that page will look like the following:

![Defining permissions in the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/52FOUrB7EcV17WYLSjdbDS/19d1360d9def0ea77cc550ba664a7748/defining-permissions-auth0-dashboard.png.png)

This configuration informs Auth0 that the glossary Web API supports only these permissions.

Next, move to the *Settings* tab and scroll down to the *RBAC Settings* section. Here, click both the *Enable RBAC* and the *Add Permissions in the Access Token* toggle buttons, as in the following picture, and don't forget to click the *Save* button at the end:

![](https://images.ctfassets.net/23aumh6u8s0i/49AQnZIW5pP4wBIHA4sV9i/2c476e2508ff68fde80061b6973016ca/enabling-rbac.png)

These settings will enforce the evaluation  of roles and permissions assignments during the user login.

> Although we will not use roles in this article, you still need to enable RBAC (Role-Based Access Control) support.



<details>
  <summary>Permissions vs. scopes</summary>
When defining the API permissions in the Auth0 Dashboard, you find the term *scope* next to the term *permission*. You may think that they are synonymous, but they actually aren't. Both describe the actions that can be performed on a resource, but they are used in different authorization scenarios.

**Permissions** are used in a [first-party authorization scenario](https://auth0.com/docs/applications/first-party-and-third-party-applications#first-party-applications), i.e., when the same organization or person controls both the client and the server applications.

**Scopes** are used in a [third-party authorization scenario](https://auth0.com/docs/applications/first-party-and-third-party-applications#third-party-applications), i.e., when different organizations control the client and the server applications.

In the latter scenario, the client application asks for one or more permissions to operate on a specific resource on behalf of the user. This requested permission is a **scope**. Usually, scopes limit what an app can do on behalf of the user, and the user may grant them to the application or not.

Scopes have been [introduced by OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) in the context of delegated authorization.
</details>

## Checking Permissions in an API

As the next step, you need to check that the user calling your API has the proper permissions. You can accomplish this task by defining one or more authorization policies and applying them to the controller or the methods that implement your ASP.NET Web API.

An **authorization policy** is a set of requirements that users or applications must meet in order to be allowed to perform an action on a resource. Let's see how you can define and apply an authorization policy in practice.

### Registering an authorization policy

To define an authorization policy for the glossary Web API, open the `Startup.cs` file in the root folder of the project and append the following code to the body of the `ConfigureServices()` method:

```csharp
// Startup.cs

// ...existing code...

namespace Glossary
{
  public class Startup
  {
    // ...existing code...
    
    public void ConfigureServices(IServiceCollection services)
    {
      // ...existing code...
      
      //👇 new code
      services.AddAuthorization(options =>
      {
        options.AddPolicy("WriteAccess", policy => 
                          policy.RequireClaim("permissions", "create:term", "update:term"));
        options.AddPolicy("DeleteAccess", policy => 
                          policy.RequireClaim("permissions", "delete:term"));
      });
      //👆 new code
    }
    
    // ...existing code...
  }
}

```

You invoked the `AddAuthorization()` method to configure the ASP.NET authorization service. To this purpose, you defined two authorization policies via the `AddPolicy()` method of the `options` parameter. Each policy has a name and a lambda expression. For example, the `WriteAccess` authorization policy is defined by requiring the `permissions` [claim](https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims) in the access token whose value can be `create:term` or `update:term`. Similarly, for the `DeleteAccess` policy.

### Authorization policy approaches

You defined two authorization policies based on the permissions you defined for the API in the Auth0 Dashboard. Both policies are based on requiring the existence of claims with specific values. This is the simplest way to define an authorization policy in ASP.NET. It is usually referred to as [claim-based authorization](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/claims).

If you have more complex criteria for defining your authorization policies, you need to use the [policy-based authorization](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies) approach. For example, if you want to be sure that the issuer of the `permissions` claim is your [Auth0 tenant](https://auth0.com/docs/get-started/create-tenants), you can define your `WriteAccess` authorization policy as follows:

```csharp
options.AddPolicy("WriteAccess", policy => 
                    policy.RequireAssertion(context =>
                       context.User.HasClaim(claim =>
                         (claim.Type == "permissions" &&
                          (claim.Value == "create:term" ||
                           claim.Value == "update:term") &&
                          claim.Issuer == $"https://{Configuration["Auth0:Domain"]}/"
                         )
                       )
                    )
                  );
```

In this case, you used the `RequireAssertion()` method to build a boolean expression that evaluates your specific criteria. In particular, this criteria checks that the `Issuer` property of the claim matches the URL of your Auth0 tenant.

> Note that claim-based authorization is just a specialized case of policy-based authorization.

If you have more specific needs, you can even [customize the built-in ASP.NET authorization middleware](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/customizingauthorizationmiddlewareresponse).

### Applying an authorization policy

Once you define and register your authorization policies, you can apply them in your Web API. Applying an authorization policy is just a matter of passing parameters to the `Authorize` attribute. So, open the `GlossaryController.cs` file under the `Controllers` folder and apply the changes outlined in the following:

```csharp
// Controllers/GlossaryController.cs

// ...existing code...

namespace Glossary.Controllers
{
  [ApiController]
  [Route("api/[controller]")]
  public class GlossaryController : ControllerBase
  {
    // ...existing code...

    [HttpPost]
    [Authorize(Policy = "WriteAccess")]    //👈 changed code
    public ActionResult Post(GlossaryItem glossaryItem)
    {
      // ...existing code...
    }

    [HttpPut]
    [Authorize(Policy = "WriteAccess")]    //👈 changed code
    public ActionResult Put(GlossaryItem glossaryItem)
    {
      // ...existing code...
    }

    [HttpDelete]
    [Route("{term}")]
    [Authorize(Policy = "DeleteAccess")]    //👈 changed code
    public ActionResult Delete(string term)
    {
      // ...existing code...
    }
  }
}
```

This way, you are requesting the ASP.NET authorization middleware to evaluate a specific policy to authorize the execution of the related controller's method.

Your Web API is ready to run and check permissions!

## Testing Permissions

To test the new glossary Web API, you are going to simulate users accessing the endpoints with different permissions. For this simulation, you will interact with the API through the Swagger UI by providing an access token. So, launch the Web API by typing `dotnet run` in a terminal window and point your browser to [https://localhost:5001/swagger](https://localhost:5001/swagger).

### Testing access without permissions

Let's try to access a protected endpoint with an access token not bound to any permissions. Go to the [API section](https://manage.auth0.com/#/apis) of your Auth0 Dashboard, select the API related to the glossary app, and select the *Test* tab. Here you can get a token to test your Web API by clicking the *Copy Token* icon as shown in the following picture:

![Copy access token](https://images.ctfassets.net/23aumh6u8s0i/1FENUfKNw5FrmexhvdWwv5/bb1c283a019dc0fd7322e357efd1bdb2/copy-token.png)

Now, head back to your browser and click the *Authorize* button. A window dialog opens, as shown in the following picture:

![Bearer token in Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/18f9kh3tBXiOMbxjSA7j1k/c0ab1d1475b75ef51a50a1009ea3c5c1/access-token-swagger-ui.png)

Paste the token you copied from the Auth0 Dashboard into the text box and click *Authorize*.

> To learn a bit more about the Swagger UI, check out [this article about ASP.NET Web API authorization](https://auth0.com/blog/aspnet-web-api-authorization/).

Now, try to add a new glossary term through the `POST` action. You should get a negative response from the server similar to this one:

![Forbidden action on an endpoint](https://images.ctfassets.net/23aumh6u8s0i/2jJfEWsECwVKy9qwcy7Nyk/182e158601d78774ee3fd633028badea/forbidden-action-on-endpoint.png)

Notice that, this time, you didn't receive the `401 Unauthorized` HTTP status code. You received the `403 Forbidden` status code. This denotes that you are providing an access token, so you are authorized to access the application, but you don't have the required permissions to perform this specific action.

You can verify your current permissions by visiting [jwt.io](https://jwt.io/) and pasting your access token there. This tool allows you to decode your access token. You will discover that the `permissions` claim shown in the payload section is an empty array, as in the following picture:

![Empty permissions claim in JWT](https://images.ctfassets.net/23aumh6u8s0i/5bMNrF4vS9iYs3hQuxCMe2/d8bffd83f61373f5b9a6e2b0d69691b6/empty-permissions-claim-in-jwt.png)

### Testing access with writing permissions

Let's create an access token with the required permissions for adding a new term.

Back in your API configuration page on the Auth0 Dashboard, select the *Machine to Machine Applications* tab. You'll get a list of applications, some of them with the *(Test Application)* label in the name. These applications are automatically created by Auth0 when you create an API there. They are meant as test clients from your API. One of them should have the *Authorized* switch on. Click the dropdown next to it and check the `create:term` and `update:term` permissions in the section that will be shown:

![Writing permissions assignment](https://images.ctfassets.net/23aumh6u8s0i/1noHOvxBZaRERXAJ9SpPt2/849b32e5f54524cc3e6f3e58eb1f3578/assign-writing-permissions.png)

Then, click the *Update* button, move again to the *Test* tab, and copy the new token that has been generated for you. Now, in the Swagger UI of your Web API, click the *Authorize* button again. This time the following window should appear:

![Changing the access token](https://images.ctfassets.net/23aumh6u8s0i/1WKMrki5ZtwLPvBKmoQ1Gv/b276253e73ed5848f804ac69a37718d3/changing-access-token.png)

Click the *Logout* button and paste the new access token in the text box that appears.

At this point, try again to add a new term to the glossary through the `POST` action. Now you should get a successful response from the server.

If you decode your new access token in [jwt.io](https://jwt.io/), you should see that the `permissions` claim now contains the two permissions you assigned:

![Writing permissions in JWT](https://images.ctfassets.net/23aumh6u8s0i/WVVEcOwuIeuB73aYKu0Q0/e8a722919757b259befd52ddc09dfdf5/writing-permissions-in-jwt.png)

If you attempt to delete the newly created term with the same access token, you get the `403 Forbidden` status code as before. In fact, your access token doesn't contain the deleting permission.

### Testing access with deleting permissions

To be authorized to delete a glossary term, you need to grant the deleting permission to the test application. So, go back to the *Machine to Machine Application* tab of your API configuration on the Auth0 Dashboard and open the permissions section of the test application again. Check also the `delete:term` permission and click the *Update* button. Now, in the *Test* tab, copy the new access token and head back to your browser.

In the Swagger UI of your Web API, replace your current access token with the new one by using the *Authorize* button. Then, delete the glossary term you added earlier by using the `DELETE` action. This time your attempt should be successful!

## Recap

In summary, you learned that permissions give you more granular control over access to your Web API. You discovered how to define permissions associated with your API in Auth0 and how to define and register authorization policies in your ASP.NET application. You saw that checking permissions in your API controller is a matter of adding a parameter to the `Authorize` attribute. You used your test client application on the Auth0 Dashboard to generate access tokens with the required permissions. Finally, you used the Swagger UI to test your Web API with access tokens having different permissions.

You can download the final code of the sample application from [this GitHub repository](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/add-permission).


Permission-Based Security for ASP.NET Web APIs

Learn how to secure an ASP.NET Core Web API by granting access only to authorized users through Auth0 authentication and authorization services.

Having control over who can access your API is a necessary requirement to make your application secure. This article will show you how to restrict access to your ASP.NET Core Web API to authorized users only.

## Setting up the Web API Application

Let's start by setting up the ASP.NET Core Web API application to be protected. You can download a glossary Web API from [this GitHub repository](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/starter) by running the following command in a terminal window:

```bash
git clone --branch starter --single-branch https://github.com/auth0-blog/glossary-web-api-aspnet.git

```

This ASP.NET application provides you with a CRUD Web API to manage a glossary of terms. You can learn the details of its implementation by reading [this article](https://auth0.com/blog/building-aspnet-web-api).

Once you download the application, move to the `glossary-web-api-aspnet` folder and launch it by typing `dotnet run` in a terminal window. By pointing your browser to `https://localhost:5001/swagger`, you should see a page like the following to interactively test the APIs:

![Swagger UI for Web API](https://images.ctfassets.net/23aumh6u8s0i/39X3FZbdleAybhhvH5hCV7/b0276f9319a0a8110fcffc1dd583f602/webapi-swagger-ui.png)

The Web API application allows you to get a list of term definitions or a single term definition. It also lets you create a new definition and modify or delete an existing one.

The current implementation of this glossary Web API allows anyone to perform all the available operations on the glossary. Most probably, you want to allow everyone to get a single glossary item or the full glossary. Still, only authorized users should be enabled to create, update, and delete glossary items.

Let's go and see how to protect these three actions by integrating your ASP.NET Core Web API with [Auth0](https://auth0.com) services.

## Registering the Web API with Auth0

To start securing your API with Auth0, you need an Auth0 account. If you haven't got one, you can <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one</a>. Now, you can register your Web API through the [Auth0 Dashboard](https://manage.auth0.com/).  Move to the [API section of the Dashboard](https://manage.auth0.com/#/apis) and follow these steps:

1. Click on *Create API*
2. Provide a friendly name for your API (for example, *Glossary API*) and a unique identifier in the URL format (for example, *https://glossary.com*)
3. Leave the signing algorithm as RS256 and click the *Create* button

These steps make Auth0 aware of your Web API and will allow you to control access.

> **Note**: While you are in the Auth0 Dashboard, take note of your Auth0 domain. You will need it soon. This is a string in the form `YOUR-TENANT-NAME.auth0.com` where `YOUR-TENANT-NAME` is the name you provided when you created your account with Auth0. For more information, [check the documentation](https://auth0.com/docs/getting-started/the-basics#domains).

<details>
  <summary>Using the Auth0 CLI</summary>
As an alternative to the Dashboard, you can use [the Auth0 CLI](https://auth0.com/blog/introducing-auth0-cli/) to register your API with Auth0.


In this case, [install the CLI on your machine](https://github.com/auth0/auth0-cli#installation) and [configure it to access your Auth0 tenant](https://github.com/auth0/auth0-cli#login). Then, run the following command in a terminal window:

```bash
auth0 apis create --name "Glossary API" --identifier https://glossary.com --scopes ""
```

This command creates an entry for your API with the name *Glossary API* and the unique identifier `https://glossary.com`. You are not specifying any [scope](https://auth0.com/docs/scopes) for this application right now.

Running this command has exactly the same effect as registering your API through the Auth0 Dashboard.

After the registration, you will get an output like the following:

```bash
=== <YOUR_AUTH0_DOMAIN> API created

  ID          60ac3b89f0cd4a003d42e850  
  NAME        Glossary API              
  IDENTIFIER  https://glossary.com   
  SCOPES  
```

Take note of the values for the `<YOUR_AUTH0_DOMAIN>` placeholder and the identifier.
</details>

## Enabling Authorization Support

The next step is to adapt the ASP.NET Core Web API application's code to use Auth0 authorization services.

### Configuring the Web API

Back in your ASP.NET application, open the `appsettings.json` configuration file and replace its content with the following:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "Auth0": {
    "Domain": "YOUR_AUTH0_DOMAIN",
    "Audience": "YOUR_UNIQUE_IDENTIFIER"
  }
}
```

Replace the `YOUR_AUTH0_DOMAIN` placeholder with your Auth0 domain and the `YOUR_UNIQUE_IDENTIFIER` placeholder with the value you provided as a unique identifier of your API (`https://glossary.com`, if you kept the value suggested above).

### Integrating with Auth0

In order to interact with the Auth0 authorization services, your application needs to be able to handle tokens in the [JWT](https://jwt.io/) (*JSON Web Token*) format. You can accomplish this by installing the `Microsoft.AspNetCore.Authentication.JwtBearer` library. Move to your application folder and type the following command in a terminal window:

```bash
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
```

When the installation is complete, open the `Startup.cs` file and add the `JwtBearer` namespace. The `using` section of the file should look as shown below:

```c#
//Startup.cs
...existing code... 
using Microsoft.OpenApi.Models;
using Microsoft.AspNetCore.Authentication.JwtBearer; //👈 new code

namespace Glossary
{
  //...existing code...
}
```

In the same file, replace the `ConfigureServices()` method of the `Startup` class with the following code:

```c#
//Startup.cs

// ...existing code...
    public void ConfigureServices(IServiceCollection services)
    {
      //👇 new code
      services.AddAuthentication(options =>
      {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
      }).AddJwtBearer(options =>
      {
        options.Authority = $"https://{Configuration["Auth0:Domain"]}/";
        options.TokenValidationParameters = 
          new Microsoft.IdentityModel.Tokens.TokenValidationParameters
          {
            ValidAudience = Configuration["Auth0:Audience"],
            ValidIssuer = $"{Configuration["Auth0:Domain"]}",
            ValidateLifetime = true,
          };
      });
      //👆 new code

      services.AddControllers();
      services.AddSwaggerGen(c =>
      {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Glossary", Version = "v1" });
      });
    }
// ...existing code...
```

You added the authentication service by specifying the JWT bearer scheme. You also configured the JWT handler by using the domain and audience values from the `appsettings.json` configuration file. In particular, you built the authority URL based on the Auth0 domain and set the parameters that allow the access token to be validated. Specifically, a token is considered valid if it meets the following criteria:

- it has the expected audience,
- it was issued by the expected domain,
- it is not expired.

Finally, replace the `Configure()` method of the `Startup` class with the following code:

```c#
//Startup.cs

// ...existing code...
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();
    app.UseRouting();
  
    app.UseAuthentication();  //👈 new code
    app.UseAuthorization();
  
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}
// ...existing code...
```

Compared to the previous version, you just added the `app.UseAuthentication()` statement to enable authentication for your application.

<details>
  <summary>Why do you need authentication?</summary>
You may wonder why you need to register the authentication middleware in your ASP.NET Web API. After all, you should only manage authorization. The authentication middleware is needed because it is responsible for creating the security context under which the code is running.


Also, the registration order is important: you need to register the authentication middleware before the authorization middleware.

For more details, check out the [ASP.NET Web API authentication and authorization documentation](https://docs.microsoft.com/en-us/aspnet/web-api/overview/security/authentication-and-authorization-in-aspnet-web-api).
</details>

<include src="Auth0TemplatesForDotnetCTA" />

## Securing the API Endpoints

Almost everything is ready to secure your application. You just need to protect the actions that allow clients to create, update, and delete glossary items. So, open the `GlossaryController.cs` file in the `Controllers` folder and add the `Microsoft.AspNetCore.Authorization` namespace. The `using` section of the file will look like the following:

```c#
//Controllers/GlossaryController.cs
using System;
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using System.IO;
using Microsoft.AspNetCore.Authorization;  //👈 new code

namespace Glossary.Controllers
{
  // ...existing code...
}
```

Now, add the `Authorize` attribute to the `Post()`, `Put()`, and `Delete()` methods. As an example, your `Delete()` method should become like shown below:

```c#
//Controllers/GlossaryController.cs
// ...existing code...
        [HttpDelete]
        [Route("{term}")]
        [Authorize]  //👈 new code
        public ActionResult Delete(string term)
        {
            var glossaryItem = Glossary.Find(item =>
                   item.Term.Equals(term, StringComparison.InvariantCultureIgnoreCase));

            if (glossaryItem == null)
            {
                return NotFound();
            }
            else
            {
                Glossary.Remove(glossaryItem);
                return NoContent();
            }
        }
// ...existing code...
```

As you can see, the only difference is the `Authorize` attribute.

> **Note**: You may be wondering if the order of the attributes applied to a method or to a controller class matters. Their order is internally defined, and it depends on the stage of the HTTP pipeline they are bound to and on their scope (global, class, or method scope). So, from a syntactical point of view, it doesn't matter if you put, for example, the `Authorize` attribute before or after the `Route` one.
> For more information on this point, check the [official documentation](https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/filters?view=aspnetcore-3.0).

<include src="ebook-ads/dotnetIdentity" />

## Testing the Secure Web API

In order to ensure that all works as expected, run the application, point your browser to [https://localhost:5001/swagger](https://localhost:5001/swagger), and test the GET action on the `api/Glossary` endpoint. You should get the list of term definitions as before.

### Testing unauthorized accesses

Now, try to add a new item to the glossary by using the POST action on the `api/Glossary` endpoint as shown in the following picture:

![Calling HTTP POST on the Glossary Web API](https://images.ctfassets.net/23aumh6u8s0i/2Wj5qH5QGMcZC82KC47HVM/758a0589e4254ff6a013deb48808cba7/post-webapi-swagger-ui.png)

This time you should get a `401 Unauthorized` HTTP status code, as shown below:

![Unauthorized response from the Web API](https://images.ctfassets.net/23aumh6u8s0i/4GB1MoOEZ3VoKRddc5Vwxi/0510cf8164263b15d188fc5ab5751424/unauthorized-response.png)

This means that your endpoint is protected: only authorized users can add a new definition to the list. So, in order to add a new item to the glossary, you need to get an access token from Auth0 and make a request to the API endpoint using the [Bearer Authorization scheme](https://www.rfc-editor.org/rfc/rfc6750.html).

### Testing authorized accesses

However, before going ahead, you need a way to provide your access token to the interactive web API documentation. To achieve this goal, edit the `Startup.cs` file and apply the changes shown in the following code snippet to the `ConfigureServices()` method:

```csharp
//Startup.cs
// ...existing code...
    public void ConfigureServices(IServiceCollection services)
    {

      // ...existing code...
      services.AddControllers();

      services.AddSwaggerGen(c =>
      {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyProject", Version = "v1.0.0" });

        //👇 new code
        var securitySchema = new OpenApiSecurityScheme
        {
          Description = "Using the Authorization header with the Bearer scheme.",
          Name = "Authorization",
          In = ParameterLocation.Header,
          Type = SecuritySchemeType.Http,
          Scheme = "bearer",
          Reference = new OpenApiReference
          {
            Type = ReferenceType.SecurityScheme,
            Id = "Bearer"
          }
        };

        c.AddSecurityDefinition("Bearer", securitySchema);

        c.AddSecurityRequirement(new OpenApiSecurityRequirement
          {
              { securitySchema, new[] { "Bearer" } }
          });
        //👆 new code
      });
    }
// ...existing code...
```

You added a few additional configuration options to your API's Swagger instance. In particular, you defined a security schema and added it to the generated documentation as a security requirement.

Now, restart your ASP.NET Core Web API and take a look at the web page shown at the address [https://localhost:5001/swagger](https://localhost:5001/swagger):

![Protected Web APIs in Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/1rNBChKdbCr9fKdpbbYcKR/014f6ace0411febc726959cd88ed8e6a/protected-swagger-ui-webapi.png)

You see the new *Authorize* button and the lock icon on each action. You can configure Swagger to get a more accurate UI, but this topic is out of the scope of this article. Please check out [the official documentation for more details](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#add-security-definitions-and-requirements).

At this point, let's get the access token from Auth0. The simplest way is to access [the API section of your Auth0 Dashboard](https://manage.auth0.com/#/apis) again, select the API that you created before and select the *Test* tab. In this section, you can get a temporary token to test your Web API by clicking the *Copy Token* icon as shown in the following picture:

![Copying temporary token from the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/1FENUfKNw5FrmexhvdWwv5/bb1c283a019dc0fd7322e357efd1bdb2/copy-token.png)

Now, head back to your browser and click the *Authorize* button. A window dialog opens, as shown in the following picture:

![Configure access token for Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/18f9kh3tBXiOMbxjSA7j1k/c0ab1d1475b75ef51a50a1009ea3c5c1/access-token-swagger-ui.png)

Paste the token you copied from the Auth0 Dashboard into the text box and click *Authorize*.

With this step, you have configured the interactive documentation to add the Authorization header to each HTTP request. That header's value will be the access token in the form of a bearer token.

If you try to add a new glossary term through the POST action, you should get a successful `201 Created` HTTP status code as before securing the API. The following picture shows an example of such a response:

![A successful response from the protected Web API](https://images.ctfassets.net/23aumh6u8s0i/2iY4mvFFAZGrDcpXKZiFPU/b0f0b3d576e9d0fc19e7fc7574e089a3/success-response-webapi-post.png)

Now your Web API is ready to be securely consumed by clients.

## Recap

This article showed you how to protect your ASP.NET Core Web API to prevent unauthorized users from accessing specific endpoints. You learned how to register your Web API application with Auth0, how to enable your ASP.NET application to support authorization, and how to use the autogenerated interactive documentation to test the endpoints.

You can download the full source code of the application from [GitHub](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/add-authorization).


Authorization for ASP.NET Core Web APIs

abhishek-chanda

I am a backend/platform engineer focusing on making application deployments easier.

Senior Systems Engineer

Abhishek Chanda

Learn how to implement a simple REST API with JWT Authentication in Rust using the actix web framework and Diesel.

Build an API in Rust with JWT Authentication

William Juan

I am a Frontend Developer working primarily in the web and hybrid mobile spaces. The majority of my work has revolved around the Angular ecosystem, including working with other Angular-related frameworks such as NativeScript and Ionic. My passion lies in converting a design into code and achieving a close to pixel-perfect end-product.

Frontend Developer

Improve the User Experience (UX) of an e-commerce application by implementing animations utilizing Angular animations, CSS animations, and Web Animation APIs.

Get Better Angular UX Using 4 Animation Techniques

5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

99c4080f412ccf46b9b564db7f482907?s=200 avatar

99c4080f412ccf46b9b564db7f482907?s=200

I'm currently a Senior Developer Advocate at MongoDB. I'm also a Google Developer Expert for Web Technologies and spend most my time giving talks at conferences and meetups, mentoring developers and running workshops, and creating online content to help technology professionals.

Former Auth0 Employee

Ado Kukic

Practice Go and React by building and authenticating a RESTful API with JSON Web Tokens (JWTs).

Authentication in Golang with JWTs

30b8d1b7c0dab4bb311c121a47a6aae9?s=80 avatar

30b8d1b7c0dab4bb311c121a47a6aae9?s=80

Guest Author

Vladimir Fomene

Learn how to build modern web apps using Vue.js for the frontend and a Spring Boot, Kotlin, GraphQL API for the backend.

Vue.js, Spring Boot, Kotlin, and GraphQL: Building Modern Apps - Part 2

Vue.js, Spring Boot, Kotlin, and GraphQL: Building Modern Apps - Part 1

ana-ribeiro

Ana Ribeiro

This series shows how to create a simple, full-stack web application with Angular, TypeScript, and Nest.js. Part 1: Developing the backend API with Nest.js.

Full-Stack TypeScript Apps - Part 1: Developing Backend APIs with Nest.js

332d7898dae6bc56031ac3507a0248ba

I'm a full-stack developer with a passion for technology and code. I love writing tutorials for developers to showcase a particular technology whilst building something useful at the same time. Right now  I can mostly be found developing for the front-end, playing around with Docker, or tinkering with Unreal Engine and electronics!

Developer Experience Engineer

Steve Hobbs

Learn about the Hasura platform and how their GraphQL APIs can be secured using JSON Web Tokens



If you're developing an API today for consumption by third-parties, you'd be more than forgiven for choosing the [REST interface](https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/) to develop the API, as it is a tried and tested standard for delivering data to consumers, as well as accepting changes to the data in a structured way. In more recent times, [GraphQL](https://graphql.org/) has become an attractive alternative for developing APIs thanks to its flexible, semantic, and performant nature.

But what if you'd like finer control over the details of the data exchange, including [integration with third-party authorization servers using JWTs](https://docs.hasura.io/1.0/graphql/manual/auth/jwt.html), and being able to quickly and easily set [role-based permissions at the field level](https://docs.hasura.io/1.0/graphql/manual/auth/basics.html#restrict-access-to-certain-columns)?

That's what Hasura have achieved with their [GraphQL platform](https://hasura.io/) that generates a GraphQL API over a [PostgreSQL](https://www.postgresql.org/) database. To highlight just a few of the features:

*   A PostgreSQL database schema can be designed and populated with data, using the built-in interface
*   The database can be queried using the GraphQL syntax, as well as the ability to view the GraphQL schema documentation from within the Hasura admin console
*   Roles can be assigned to individual tables and fields, as well as assigned different roles and permissions to individual operations such as selecting or inserting data
*   Authorization can be conducted using [JSON Web Tokens](https://jwt.io/), issued by a third-party authorization server such as [Auth0](https://auth0.com/)

<include src="TweetQuote" quoteText="The Hasura platform takes advantage of JWT and GraphQL technologies to provide a  platform for querying and manipulating data in a PostgreSQL database,  taking into account the role specified in the authorization token."/>

## <a class="toc-target" id="a-short-introduction-to-json-web-tokens"></a>A Short Introduction to JSON Web Tokens

From [jwt.io](https://jwt.io/introduction):

> _JSON Web Token (JWT) is an open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the **HMAC** algorithm) or a public/private key pair using **RSA** or **ECDSA**._

What this looks like in practice is a string that is made up of three parts separated by a period:

* The first part defines the header, containing information such as the signing algorithm used
* The second part is the main body of the token and includes all the claims. This could be things like the user name, expiry date, issue date, and email address
* The last part is the signature, which is derived by cryptographically signing the header and the body together to ensure that the data has not been tampered with

A JWT is issued as a result of a user authenticating with an authorization server. In the case of the Hasura platform, this JWT can then be used to authorize the request and as such can make queries and mutations depending on the claims present in the token. We will see how this works in the demo a little bit later in the article.

The compact nature of a JWT makes it easy to pass around in query strings, headers, and request bodies, or [store in a cookie](https://auth0.com/docs/security/store-tokens#understanding-sessions-and-cookies).

## <a class="toc-target" id="what-is-graphql-an-overview"></a>What is GraphQL? An Overview

GraphQL is essentially a query language that allows you to define your API in terms of types. It is datastore-agnostic and has [server-side support for many different platforms and languages](https://graphql.org/code/#server-libraries). Instead of defining your API in terms of status codes and semantic URLs, you define the types and then construct queries using a familiar but powerful syntax. As an example:

```js
{
  article {
    id,
    title,
    author {
      name
    }
  }
}
```

This describes a query for articles, returning the id, title, and the author's name. As you can see, it supports nested database objects (the author is another table in the schema, linked to from an article). Mutations can also be defined, which describe how to change data.

In addition, _multiple queries_ can be made in a single request, which is most useful when a client wants to retrieve lots of possibly unrelated data points from the server.

## <a class="toc-target" id="the-hasura-approach"></a>The Hasura Approach

The Hasura platform takes advantage of these technologies to provide a platform for querying and manipulating data in a PostgreSQL database, taking into account the role specified in the authorization token.

The Hasura console allows the user to create a database, define its schema, and populate it with data. Hasura will then generate a GraphQL API on top of this database, automatically generating the appropriate types, queries, and mutations that allow the client to completely query for and manipulate the underlying data.

Hasura takes a role-based approach to authorization, and as such an individual role's access can be narrowed down to only a subset of the overall schema (even down to the field level). As each role is mapped to certain authorization rules, it can even be prevented from running certain mutations if so desired. Furthermore, queries can be delegated to an upstream service based on the claims present in the authorization token.

[Custom claims](https://auth0.com/docs/scopes/current/custom-claims) inside the JWT are used to tell Hasura about the role of the caller, so that Hasura may enforce the necessary authorization rules to decide what the caller can and cannot do.

![Hasura GraphQL engine authorization flow chart](https://images.ctfassets.net/23aumh6u8s0i/3hUYnCpHRwjnTU6LRLl2Oc/eaf8a50276dcb8fde4eb80adf451ced9/hasura-01_arch)

[[Source](https://docs.hasura.io/1.0/graphql/manual/auth/jwt.html)]

An example of the claims used by Hasura may look like the following:

```js
{
  "https://hasura.io/jwt/claims": {
    "x-hasura-default-role": "anonymous",
    "x-hasura-allowed-roles": [
      "user",
      "anonymous"
    ]
}
```

These two keys define the possible roles as well as the default role in the absence of the ["X-Hasura-Role" header](https://docs.hasura.io/1.0/graphql/manual/auth/basics.html#add-a-simple-access-control-rule-for-a-logged-in-user). In the case of Auth0, these custom claims can be put in place using [Rules](https://auth0.com/docs/rules), a platform feature that can be used to dynamically enhance tokens as users are authenticated.

## <a class="toc-target" id="demo-querying-data"></a>Demo: Querying Data

Let's have a look at how authorization with Hasura and JWTs works in practice. A demo has been set up that will allow you to construct queries and see the role-based permissions system in action.

This demo has been pre-configured with a database that has authors, articles, tags, and a relationship table that joins many articles to many tags. Let's see how we can query for some of this data.

### Executing anonymous queries

Browse to [https://auth0-hasura-demo.herokuapp.com](https://auth0-hasura-demo.herokuapp.com/console/api-explorer), and use "hasurademo" as the access key.

![Hasura console login screen deployed with Heroku](https://images.ctfassets.net/23aumh6u8s0i/4enFGmDUiStr0A9RQ5TfnI/aeee19ffd1dd1c727a1abbb938a6f22a/hasura-01_login)

Next, you will be presented with the Hasura console:

![The Hasura console and GraphQL explorer](https://images.ctfassets.net/23aumh6u8s0i/3LlFxGsCpDUBzi78yRV1V7/1df5659f6e04290a13609f7f43e4d071/hasura-01_console-1)

The interface gives you the opportunity to specify some request headers that will be used when querying the GraphQL interface. To demonstrate how the user's role affects their ability to query and modify data, remove the `X-Hasura-Access-Key` header by clicking on the cross on the right-hand side, and enter a new header `X-Hasura-Role` with a value of "anonymous":

![Setting the X-Hasura-Role header to anonymous in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/7gltFstbQEnUuMDX3sHmLS/644c0ff9f3ca7528c8571dd3c4d437ec/hasura-01_console-2)

Now, let's make a query. Use the following query inside the Graphiql query entry area in the lower half of the screen:

```
{
  article {
    id,
    title
  }
}
```

To run the query, press Ctrl+Enter (Cmd+Enter if you're on a Mac), or click on the large 'play' button above the query panel. You will see the results of the query on the right-hand side of the screen; you have successfully managed to retrieve the results for two articles that are currently in the database!

![Hasura GraphQL API query explorer - viewing query results](https://images.ctfassets.net/23aumh6u8s0i/5LQrzHTNJ4gGvYYp0B6z5B/1d0ffbcd5f01bc76d23ab04f28d64f3a/hasura-01_console-3)

Now let's try a mutation. Alter the query so that it executes the following mutation:

```
mutation {
  insert_tag(objects:[{name:"<YOUR TAG NAME HERE>"}]) {
    returning {
      name
    }
  }
}
```

This is a mutation that inserts a new tag with your specified tag name into the database. You should replace the value `<YOUR TAG NAME HERE>` with a value of your choosing.

Running this mutation right now will return an error, letting you know that the mutation does not exist.

![Showing a failed mutation error in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/3GysSZ0xtaGnlQevp0hLgF/3394f4a20b210e1271fb8615a0433a7e/hasura-01_console-4)

This is correct since the permissions have effectively been set up so that the anonymous role cannot make changes to the database. This is also indicated by the GraphQL API docs, as it does not show any mutations that can be called by this role. To see this, click the "< Docs" button on the right-hand side of the query window to open the API documentation.

![Viewing the GraphQL API documentation explorer in the Hasura console](https://images.ctfassets.net/23aumh6u8s0i/5DNNzhAp4eAUwjhLqMga9s/091a706d83350562be740ba9b54b1f71/hasura-01_console-5)

Only queries and subscriptions are available as root types here, but no mutations.

Let's have a closer look at how permissions are set within the Hasura interface.

### Validating query permissions

To view the permissions matrix for the "tag" table:

1.  Click the "data" tab at the top of the screen
2.  Click the "tag" table on the left-hand side
3.  Click the "permissions" tab in the main part of the interface

![Viewing the permissions and roles explorer in Hasura](https://images.ctfassets.net/23aumh6u8s0i/uO6od521er4QdJvxtLmC6/ee59f070bf583ea843cfa86b701643b2/hasura-01_console-6)

You will arrive at a matrix that describes all the role permissions for the "tag" table. On this screen we can see a number of things:

*   The "anonymous" role can select data (denoted by the tick icon in the "select" column), but it can't insert, update, or delete (indicated by the cross icon in the relevant columns)
*   The "user" and "admin" roles can do everything

You can see here that, since the "anonymous" user cannot modify or insert any data, it makes sense that there are no mutations available.

Let's now switch to the "user" role and see how we can make this mutation work.

## <a class="toc-target" id="executing-authorized-queries"></a>Executing Authorized Queries

Click the "Graphiql" heading at the top of the screen to return to the query interface. Now, change the "X-Hasura-Role" request header so that its value is "user".

If you try to run the mutation again now, you will notice that it will fail for the same reason as before. This is because the "user" role needs to also provide a valid JWT in order to be properly authorized to run this mutation.

<include src="TweetQuote" quoteText="Learn how to create a GraphQL API and secure it using JSON Web Tokens using the @HasuraHQ platform"/>

### Generating a valid JWT

For the purposes of this demo, a tool has been provided to make it easy for you to generate a JWT and run this mutation.

Browse to [https://auth0-hasura-demo.now.sh/](https://auth0-hasura-demo.now.sh/) and log in with your Auth0 account. If you do not currently have one, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">register for a free account</a>.

> **Note:** In a real-world application, you would retrieve an access token directly from the authorization server when the user logs in, and use that in your requests to the GraphQL engine. This tool has been provided only as a convenience for the purposes of this demo.

![Generating a valid JWT for demonstration purposes](https://images.ctfassets.net/23aumh6u8s0i/6lI7QMcEz5nB3EbLGYsYii/112f674d24644fda68df1f7e471666ef/hasura-01_console-7)

Once logged in, you will be able to see your token. Select the entire token string and press Ctrl+C (or Cmd+C on a Mac) to copy it into your clipboard.

Before we head back to the Hasura console, let's inspect the token to see if it contains the claims that we inspect. Head to [http://jwt.io](http://jwt.io), scroll down and paste the token into the left-hand side of the screen. The right-hand side will automatically update to show you the data contained within the token, and you should be able to see that the correct Hasura claims have been included:

![Testing the JWT token at jwt.io](https://images.ctfassets.net/23aumh6u8s0i/3UghmdynnrceKJlxCu9XQ8/e066af2a85423a3f80312ab87b33dd1a/hasura-01_jwt-io)

With the token still in your clipboard, head back to the Hasura console. The way we attach this token to the request is through the standard "Authorization" request header.

Add a new header into the "headers" section, specifying the Authorization header and the JWT that you have in your clipboard as the bearer token:

![Adding the JWT to authorization request header in Hasura](https://images.ctfassets.net/23aumh6u8s0i/4wv6EC1ul56yPyI7icp2RQ/385c6bf02446601e5f1cb71dbbf12cf5/hasura-01_console-8)

Next, try running the mutation again. You should find that the query now works and that the name of the tag is being played back to you in the response:

![Authorized and successful run of previously failing mutation](https://images.ctfassets.net/23aumh6u8s0i/58rXtEu8Xe83VAv4dh8nqQ/574614e0324061ab0c7d3e6d1ace3f6f/hasura-01_console-9)

> **Note**: The "tag" database uses the tag name as its primary key. Since this demo is a cloud deployment that could potentially be used by many people, you should use your own made-up name for a tag as you cannot enter duplicate primary keys. If you have used a tag name that already exists, you will receive an error result in the query results window. Try running the mutation again with a different tag name.

Before we head away from this screen, let's expand the API docs again to show that the "mutations" root now appears and that you can browse through all the available mutations given that you are now authorized to do so:

![GraphQL API documentation explorer in Hasura showing mutations](https://images.ctfassets.net/23aumh6u8s0i/4lohzmsY0Hgy4MYWgNEuQ5/73012dbceb3010874feb695060db4738/hasura-01_console-10)

Finally, to prove that the mutation has worked we can explore the raw data in the database. Once again, click the "Data" heading at the top of the screen and then click on the "tags" table on the left.

![Raw data in Hasura after the mutation has been executed](https://images.ctfassets.net/23aumh6u8s0i/5ZVbWL8bJxXeASO1KsyRLs/85935085b9dec9ec08ff5ae29ae065c1/hasura-01_console-11)

The resulting screen will show you the data that is present in the table, and you can see that the "example-tag" entry that was created by the mutation is there.

## <a class="toc-target" id="wrapping-up"></a>Wrapping Up

In this post, you learned a bit about GraphQL and the main differences from a traditional REST API. You also had an introduction to JSON Web Tokens, how they are made up, and how easy they are to pass around.

Next, you discovered how Hasura tackles the idea of a role-based architecture when it comes to securing GraphQL APIs, and how it uses JWTs to authorize incoming requests and grant permissions to specific areas of the schema, even down to the field level.

Finally, you had a practical look at the Hasura platform, learning how to perform anonymous queries, and how to perform authorized mutations using a JWT that was issued to you by Auth0.

### Further reading

*   [Hasura.io](https://hasura.io/)
*   [Hasura GraphQL Engine Documentation](https://docs.hasura.io/1.0/graphql/manual/index.html)
*   [jwt.io](https://jwt.io)
*   [Introduction to GraphQL](https://graphql.github.io/learn/)

<include src="asides/AboutAuth0" />

## <a class="toc-target" id="about-hasura"></a>About Hasura

Based out of Bangalore and San Francisco, Hasura makes developer tools that simplify and accelerate product development.

The Hasura GraphQL engine is an open-source service that gives you instant, realtime, high-performance GraphQL for any Postgres app (including on existing databases).

Read more at [Hasura.io](https://hasura.io).


Using JWTs for GraphQL Authorization with Hasura

This article introduces the reader to reactive programming using the Spring WebFlux API.

Introduction to Spring WebFlux

fikayo-adepoju

Fikayo Adepoju is a Full-stack developer, technical writer and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0 and The New Stack blogs and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on <a href="https://www.udemy.com/user/fikayo-adepoju/">Udemy</a>.

Full-Stack Developer

Fikayo Adepoju

Learn how to create virtual reality experiences on the web using the Threejs WebGL library and the WebVR UI library.

Getting Started with the New WebVR API

avatar

Jared has worked alongside founding teams to define and deliver products which are critical to Fortune 500 enterprises and small businesses, enjoyed by consumers, and depended on by developers. Along the way, he's helped grow multiple companies from a handful of people to hundreds of employees, financial stability, and successful acquisitions. Additionally, Jared is an active contributor to open source software. He is the lead developer of Passport.js, the popular authentication framework for Node.js. Downloaded over 2 million times per month, it powers authentication for innumerable applications on the Internet. He has a portfolio of over 300 repositories freely available on GitHub.

Jared Hanson

From basic website authentication to implementing an OpenID Connect server and API authentication: This article covers 3 IAM examples to support your Digital Transformation.



**TL;DR:** We recently [hosted a webinar](https://resources.auth0.com/webinars/3-iam-examples/) that covered modern identity management and what it takes to implement both Authentication and Authorization to support your Digital Transformation. In this article, we'll cover these implementations ranging from basic authentication, to an OpenID Connect server, and API authentication.


## Introduction
Identity and Access Management (IAM) encompasses the security protocols and processes that allow the correct users to access the correct content, at the correct times.  Cloud-based IAM providers, such as _Auth0_, have created simpler and more intuitive ways of managing user access, and they form an important part of **digital transformations.**

<include src="TweetQuote" quoteText="Identity and Access Management (IAM) is the security and process that allows the correct users to access the correct content, at the correct times."/>

Digital transformation, for those unaware, is not just a buzzword. It encapsulates the process of heavily utilizing modern, digital technologies to radically change businesses.

> Look beyond the hype and you'll find a daunting task at the heart of digital transformation. Rather than focusing on any single IT project, digital transformation describes a series of projects that, together, change every facet of an organization, from back office operations to customer interactions, often with the end goal of making these different processes intrinsically linked.

[http://www.itpro.co.uk/strategy/28047/what-is-digital-transformation](http://www.itpro.co.uk/strategy/28047/what-is-digital-transformation)

As we go through this article, we will cover three _IAM_ use cases. Firstly, we will cover implementing authentication on a basic website. This is the situation most people will find themselves in and the most common use case of the three. Once we've covered basic website authentication, we will move onto standard federated logins.

The second scenario we will cover is _**Enterprise SSO**_. We shall create a fake example company named _Acme,_ whos enterprise customers demand a way of logging into Acme's various services without having to remember a range of username and passwords. By using OpenID Connect, we will show how they can allow their customers' employees to log in with corporate credentials.

Finally, we will cover API integration. When we want to allow our customers to integrate our service into their line-of-business applications in custom ways.


## A Basic Website
Something we're all familiar with is the basic user registration and login that we find on our favorite websites. To access various areas and features of most websites, we usually have to create an account with them. From a high level, all this consists of is a database containing our usernames/email addresses and a complex hash of our passwords (hopefully).  Throughout this article, we'll use an example data model in which crucially, the core Users table will never change the schema, only the data references will change. The basic data model looks like this:

![Basic Data Model](https://images.ctfassets.net/23aumh6u8s0i/74wMh29yR35x1gyeASUrmv/9e037c843a6ff03b59be3420a7945677/basic-data-model)

Our sample data model is that of a simple project management tool, in which Users own Projects. Very basic. Now, what we need is a way for our users to register their details for our application.

![Basic Registration](https://images.ctfassets.net/23aumh6u8s0i/3L7FmaYEjSOGrUdOexyRdw/9e8c66dd6e21383e06694f5db8490da6/basic-registration)

As you can see in the image, our app now contains a standard sign up for new users to register for our service. From a back end perspective, the form uses a `POST` action to submit the form data to our `/signup` resource. Our back end then writes this data to our chosen database and forwards the user onto the specified route upon successful completion. Once we have a user signup implemented, a user login is the next thing we need to address. The basic login flow for our simple web app looks like this:

![Basic Login](https://images.ctfassets.net/23aumh6u8s0i/1Ku7YSRGdgbf5xOoEpUnxQ/55c563b1aaa309b085de6fcfa8a72b6f/basic-login)

In our login flow, users submit their email address and password, which issues a `POST` request to our `/login` resource. Our application back end takes the credentials supplied, issues a database lookup and ensures the details are correct. If so, our app will issue a HTTP forward request onto the specified resource, containing a Session Cookie.

In the image above, you can see that the Session Cookie is set as a HTTP Header, and is actually the most important factor in this flow. The Cookie will contain tokenized information about our users perhaps including metadata such as the user's name and avatar, so as to reduce database hits going through our web app. Besides containing the user's metadata, the Session Cookie is (more importantly) also the authorization credential for all subsequent requests as the user browses our application.

With this implemented, our application now has a basic user authentication system set up. Being basic, there are many features that we haven't addressed here, but that would really need implementing. Password hashing, password complexity verification, password reset functionality, and multi-factor authentication to name a few. Luckily, by using a system such as [Auth0's Hosted Login](https://auth0.com/docs/hosted-pages/login), we save the worry of having to implement these, as they come as standard. Out of the box, Auth0 offer the features mentioned above plus many more. You can have a fully functional user management system setup in minutes.


## Single Sign On (SSO) for Enterprise
If you've used services such as Amazon Web Services, Slack, GitHub or Salesforce, you will notice that they all have a Single Sign On (SSO) implementation so that users can access those services with their corporate credentials. As we add SSO federated capabilities into our sample application, we do have one constraint in that (as mentioned above), we do not want to change the data table schema.

![SSO Data Model](https://images.ctfassets.net/23aumh6u8s0i/6M9ZrX0pYtMQlLySKJ7j0r/fd0e804720e293fda0d1c9c2f1026740/sso-data-model)

Our `Users` and `Projects` tables do not change, but the relationships evolve to include our external identity providers.

For our Federated SSO implementation, we're going to implement an _Identifier-first_ login prompt. Our application will only ask for an email address for the user:

![SSO Login Prompt](https://images.ctfassets.net/23aumh6u8s0i/5uaqLWmRI3n3Z0TKysWTcg/dfb0e87190ced85da967c708cb216f31/sso-login-prompt)

The point of this is to look up the SSO identity provider associated with this email address, which in this case is **_cotoso.com_**, so the user will be redirected there to log in.

![SSO Flow](https://images.ctfassets.net/23aumh6u8s0i/4ovSoo6JhxjhQnaDBYNRcv/b1a5209e2608147b29e1cfd70fe7b5cc/sso-flow)

As shown in the image above:  once the user _(sally@contoso.com)_ enters her email address, our application determines that _contoso.com_ is our Identity Provider and redirects her there. Sally then logs into her _contoso.com_ corporate account, and _contoso.com_ verifies it. She is then redirected back to our application with access granted.

As part of this OpenID Connect authentication response, the `code` returned in the OpenID Connect Auth Response above is exchanged for an `ID Token`. The `ID Token` is what conveys the identity information from _contoso.com_ to our application, and looks like this:

``` json
{
  "iss": "https://id.contoso.com",
  "sub": "2482899761001",
  "name": "Sally",
  "email": "sally@contoso.com"
}
```

As with all ID Tokens, there is an _Issuer_ and an _Identifier_.  The Issuer being `https://id.contoso.com`, and the _Identifier_ being the subject `"sub": "2482899761001"`. In the auth flow above, our application (acme.com) will now look at this ID Token, identify Sally, and forward her onto our Dashboard, setting a Session Cookie for future requests.

From a database point-of-view, this SSO flow will look like this:

![SSO Database Flow](https://images.ctfassets.net/23aumh6u8s0i/3l5n9ubTlVC3BL9zbbmZJe/7d8aeb7f309d3477d96a3313d9b47748/sso-database-flow)

Firstly, our application will perform a lookup for the identity provider _contoso.com_, and redirect Sally to that login. Once Sally has logged in on _contoso.com_ and has been redirected back to our application, one of two things will happen. If Sally has never registered with our application before, a User record will be created for her, with the information returned from _contoso.com_. This would replace the sign up step we implemented in the basic example above. Our application will then associate the external identity with the new user record for find operations on subsequent logins.

![SSO Final Step](https://images.ctfassets.net/23aumh6u8s0i/20d076SSRPax813EDFIfYO/3f23fac0b59109b8a9d04c8a68faeb46/sso-final-step)

Similar to our earlier basic example, upon successful login, a _Session Cookie_ is set to portray the information required for subsequent requests.

With the above, we now have Single Sign On implemented on our acme.com sample application. Worth noting here is that in this SSO implementation, we have chosen an identifier-first login prompt with no option for a password. In reality, we would need to implement a password option for users that have existing non-federated accounts. Beside this, we should also implement a SAML integration, and support for account linking an unlinking.

By choosing to use an IDaaS provider like _Auth0_, we can get all of these features, plus many more straight out of the box.  Using [Auth0 for SSO](https://auth0.com/single-sign-on) allows us configuration of any enterprise connection, including Active Directory, LDAP, ADFS, SAML, and more with just a few lines of code.


## API Authorization
For the final implementation example of this article, we're going to look at API Authorization. We need to implement API auth so that our customers can integrate our service into their applications in ways not offered as standard, and to allow them deeper integrations. Once again, let's take a look at our data model, now including API auth:

![API Auth Model](https://images.ctfassets.net/23aumh6u8s0i/4NRyLQsRvkuyFmq64xuNeN/d0b5238abf314ac3f4051da5db971a17/api-auth-model)

Although the model now looks slightly more complex, following our aforementioned constraint; our `Users` and `Projects` schemas have not been changed. The schemas for SSO providers have not changed either. What has changed are the tables on the left, which introduce support for other people getting access to _Acme's_ APIs. If you are familiar with Facebook sign-on or GitHub etc, the terms above are fairly typical. `Clients` are the applications a user may build/use to access APIs and services, `Resource Servers` are the APIs themselves, and the Authorization Grants `(AuthZ Grants)` track the permissions that have been granted between the users and the applications.

For our API Authorization example, we are going to imagine that our sample company (Acme.com) have a customer named _Fabrikam.com,_ who wish to allow their customers to pull a list of their `Projects` from the _Acme_ API to display on their own dashboard.

From a simple button on the _Fabrikam.com_ website, their customers will be redirected through an OAuth2 Authorization request to the _Acme_ website, returning an Auth code on successful submission. Using the OAuth2 auth flow of [Client Credentials Grant](https://auth0.com/docs/api-auth/tutorials/client-credentials), this Auth code will then be swapped for an **Access Token** and used in the web application's _Authorization Header_ using the `Bearer` protocol.

Let's take a look at how the API Auth flow works visually:

![API Auth Login](https://images.ctfassets.net/23aumh6u8s0i/49pbvFGduF9VwuFevWGf66/e5c9bc8dc3632dbb826ff32e02b5cb46/api-auth-login)

As you can see from the image above, the customer of _Fabrikam.com_ clicks on the 'Connect to Acme' button on their Dashboard.  This click then issues a GET request to the `/connect/acme` route, which from the back end initiates an OAuth2 request to the _Acme.com_ server. The _Fabrikam.com_ customer is then prompted to log in using their _Acme_ credentials. On success, the _Acme.com_ server issues the OAuth2 Authorization Response to the `callback_url` specified in the initial request. In a similar manner to the _OpenID Connect_ example above, this response contains a `code` that will be exchanged for an **Access Token:**

![API Auth Login Response](https://images.ctfassets.net/23aumh6u8s0i/36WBGudxJpP0g6U9RaRb32/0dfc5f2e368f90c40054592d672aabcb/api-auth-login-response)

Following the [Client Credentials Grant flow](https://auth0.com/docs/api-auth/tutorials/client-credentials), the _Fabrikam.com_ back end swaps the above code for the Access Token needed for subsequent API requests.  The Access Token returned will have the following appearance:

``` json
access_token = eYJ0eXAi0...

{
  "iss": "https://www.acme.com",
  "aud": "https://api.acme.com/v1/",
  "sub": "501",
  "scp": [ "read:projects" ]
}
```

This _Access Token_ is similar to the _ID Token_ shown in the previous example, but instead of just identifying the user, it is also responsible for allowing _Fabrikam_ to make API calls subsequent to this Authentication event happening. This Token contains _Acme_ as the issuer, the API route to be used, the `subject` referring to the user id of "502", and the request _permissions_ in the `scope`. With the _Access Token_ now available to _Fabrikam.com_, it is used with requests for the customer's `Projects` from the _Acme.com_ API.

![API Auth Authd Reqs](https://images.ctfassets.net/23aumh6u8s0i/59HhtjSyKjTQST9ItgwwoL/8e3d373768fb5cfcb94297f2395ff731/api-auth-authd-reqs)

As the image shows, _Fabrikam_ sends the encoded token in the `Authorization` Header of the request, using the `Bearer` protocol, in all subsequent API requests.  The _Acme.com_ API successfully returns the customer's `Projects` which are listed in the Dashboard, as shown. That brings to a close the OAuth2 Client Credentials grant for API Auth example. However, we can take this a step further still. What if we wanted to combine this API Auth with the Enterprise SSO implementation in our previous example?

There may arise a scenario in which  _Fabrikam.com_ want to integrate with _Acme's_ APIs, but a user at _Acme_ authenticates with corporate credentials for _Contoso.com_ (who is an enterprise customer) as within our previous example. The flow becomes a multi-step process, with the first request coming from _Fabrikam_ to _Acme_, then _Acme_ to _Contoso_, with the responses flowing back in the opposite direction, back to _Fabrikam._. The interesting point of this scenario is that _Acme_ is acting as both an Identity Provider (when providing API authorization), and a Relying Party (when it's consuming identity information). This pattern may sound complex, but it is a very common scenario. Most SaaS companies both provide services, as well as authenticating users from other companies, meaning they have to implement both sides of the protocol (client and provider). The following diagram shows this implementation layout:

![OAuth OpenID Combine](https://images.ctfassets.net/23aumh6u8s0i/6WZAjqTn3OMo2eRyuLgvCS/1d678ed2c67c51061ddb1dfbb8773e90/oauth-openid-combine)

<include src="TweetQuote" quoteText="OAuth 2.0 and OpenID Connect have the same protocols because OpenID Connect is just an extension of OAuth."/>

Happily, as you will have noticed throughout this article, OAuth 2.0 and OpenID Connect have the same protocols, because OpenID Connect is just an extension of OAuth. This saves us a lot of hassle on implementation. At this point, with Authentication becoming a more prominent feature, it might be worth setting up a single, centralized server to handle all of the Auth requests coming through our app _(Acme)_.

If we revisit our data model, we can see that all of the tables in our model, except for the `Projects` table, can be treated as a separate concern, and become our authentication server:

![API Auth Model Pattern](https://images.ctfassets.net/23aumh6u8s0i/6jcNbD9NpTsH1E5Z9JcNtL/fd08c21e843f5af8e3944886aa3047af/api-auth-model-pattern)

We can take advantage of this in our architecture by creating the aforementioned centralized Auth server on a subdomain such as `id.acme.com`, and piping all of our Authorization / Authentication requests through there. The applications authenticating and being granted authorization through this centralized server may be third-party applications, such as _Fabrikam.com_ or _Contoso.com_, but also internal applications such as `app.acme.com`. Setting up this single centralized server is a nice and clean way to solve a lot of Auth challenges, with a single protocol and a single implementation. The architecture for this server could look like the following:

![Centralized Auth Server](https://images.ctfassets.net/23aumh6u8s0i/2hj6ZSI6wVtHmguWHPlEHq/8180c2f0e4abff657db1f05cb9536ecb/centralised-auth-server)

So with this, we have a fully functional OAuth 2.0 server implementation. Whilst this implementation is entirely functional, there are a few extra features not included in this example, that you would want to implement in the real world. One of the biggest is a _Consent Prompt_ ensuring users have the options of granting the application access, such as the following:

![OAuth2.0 Consent Prompt](https://images.ctfassets.net/23aumh6u8s0i/71FwyIRzi8zepAO1e0g4fu/388e0dfbe33ab932a3467b5e7fc3b142/consent-screen)

Besides this, consent and token revocation is also a must-have feature that would need implementing. Lastly, token introspection and JWTs for stateless authorization are both desirable features one would ideally implement.

If you wanted a fully-featured OAuth 2.0 server with all of the functionality mentioned above, it is definitely worth checking out an IDaaS provider to save you all of the implementation hassles. [Auth0](https://auth0.com/docs/protocols/oauth2) offers out of the box, fully featured OAuth 2.0 implementations that take care of all of the architecture above, plus offer more features and functionality; and all implemented without having to build and manage it yourself.



<include src="asides/AboutAuth0" />


3 IAM Examples to Support Digital Transformation

1097492785caf9ffeebffeb624202d8f?s=200 avatar

1097492785caf9ffeebffeb624202d8f?s=200

Prosper is a great speaker, community leader, open source hacker, technical consultant, and a fervent Developer Advocate. He is a full-stack software engineer who has worked on biometric, health and developer tools. Prosper recently co-founded a startup called Eden that’s focused on improving the quality of lives in Nigeria and currently leads the engineering team. He also co-founded forloop, the largest developer community in Africa.

Prosper Otemuyiwa

Learn how to build and secure RESTful APIs with KeystoneJS

Developing Web Apps and RESTful APIs with KeystoneJS

eHk3ciM

I am the Group Manager, Developer Content at Okta, and a Google Developer Expert in Web Technologies and Angular. I'm passionate about identity, authentication, constant learning, and developer communities. As a developer advocate, engineer, mentor, and international speaker, I love learning from and sharing with other inhabitants of the tech space.

Group Manager, Developer Content

Kim Maida

Build an app to learn about the power and flexibility of RxJS in Angular while exploring speech recognition with Web Speech API.

In this tutorial series, we'll learn how to build a small app with some big concepts. We'll cover reactive programming with [Reactive Extensions (Rx*)](http://reactivex.io/), JS framework component interaction in [Angular](https://angular.io), and speech recognition with the [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API). The completed Madlibs app code can be found at [this GitHub repo](https://github.com/auth0-blog/madlibs).

---

In this part, we will cover the following:

* Introduction to reactive programming with Rx* and observables
* Setting up our Angular app

Let's get started!

## What We'll Learn About

The concepts and tools we'll use and learn about include:

* Component communication in [Angular](https://angular.io) JavaScript framework
* Managing streams with [RxJS](http://reactivex.io/rxjs/) ReactiveX for JavaScript (packaged with Angular)
* [Annyang](https://github.com/TalAter/annyang) library for [Web API Speech Recognition](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition)
* Accessing a prebuilt [Node API](https://github.com/kmaida/madlibs-api) to generate random words

Let's begin with some core concepts to facilitate the use of these tools.

## Reactive Programming with RxJS and Observables

[Angular](https://angular.io) brought the ReactiveX [RxJS](http://reactivex.io/rxjs/) library to the forefront for JavaScript Single Page Application (SPA) developers. RxJS is packaged with Angular, and while it was unfamiliar to many at first, the concept of reactive programming with _observables_ in JS has gained traction and popularity with increased Angular adoption.

### Observables Are Streams

_Observables_ are a vital part of RxJS and now Angular. When learning about observables, the first concept to reconcile is that observables are _streams_. What does this mean?

Consider an array. An array is a collection of values. With a normal array, you theoretically have the collection of all values available to you from the beginning. Of course, we know this isn't always the case: in fact, it's common practice to _push_ additional values to an array in response to events, or to create new arrays _from_ other arrays with methods like [map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map), [filter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), and [reduce](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce). Traditionally, if we do this with a normal array, we need to use _callbacks_ in order to tell our scripting code that the array has a new value.

On the other hand, an observable "stream" represents a _collection over time_. A stream may (or may not) have an initial value, and over time, more values are added to it. We can _subscribe_ to the observable stream to be notified whenever a new value has been added. This is an ideal way to react to collections over time.

<include src="TweetQuote" quoteText="An observable is a stream that represents a collection over time."/>

For example, say we have a shopping cart. Every time a user successfully adds an item to their cart, we then want to run some code. (This code might display a toast with the name of the item, update a count of all items in the cart, update the cart subtotal, etc.) We could do this with a state container such as [Redux](http://redux.js.org/) or [@ngrx/store](https://github.com/ngrx/platform/blob/master/docs/store/README.md), or we could simply use an observable and subscribe to it to react each time a new value is added.

We'll implement several observables in the app that we'll build in this tutorial. To see additional examples right now, look over the [Observables section of the Glossary of Modern JavaScript Concepts](https://auth0.com/blog/glossary-of-modern-javascript-concepts/#observables). You should also check out [Rob Wormald's](https://twitter.com/robwormald) ["Everything is a Stream" slides](http://slides.com/robwormald/everything-is-a-stream) and [presentation](https://www.youtube.com/watch?v=UHI0AzD_WfY).

### Reactive Programming and RxJS

[ReactiveX, or Rx*](http://reactivex.io/rxjs/), is an API for asynchronous programming with observable streams. The JavaScript implementation is [RxJS, which is available on GitHub](https://github.com/reactivex/rxjs). As mentioned, Angular comes packaged with RxJS, so it's to our great advantage to make use of it wherever it might help.

_Reactive programming_, in a nutshell, is based on propagating and responding to incoming events over time in a [declarative](https://auth0.com/blog/glossary-of-modern-javascript-concepts/#imperative-declarative) manner. Observables, which are streams of collections over time, are ideal for this.

<include src="TweetQuote" quoteText="Reactive programming is based on propagating and responding to incoming events over time, declaratively."/>

You can read more about [reactive programming here](https://auth0.com/blog/glossary-of-modern-javascript-concepts/#reactive-programming).

## Web Speech API

The [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API) is an in-draft feature that enables the incorporation of voice data into web apps. It's still an [experimental technology](https://dvcs.w3.org/hg/speech-api/raw-file/tip/webspeechapi.html) at the time of writing, however, so cross-browser support is limited.

For our app, we're specifically interested in the [speech recognition](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition) interface of the Web Speech API. This technology allows the browser to start listening via the user's microphone, assess speech using language and grammar dictionaries, and then execute functionality (as defined by the developer) in response.

At the time of writing, this is [only supported in Chrome](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition#Browser_compatibility), so we will build our app with progressive enhancement in mind.

We will use the lightweight [Annyang](https://github.com/TalAter/annyang) JS library to work with speech recognition more easily in our application.

## What We'll Build

We're going to build an [ad libitum](https://en.wikipedia.org/wiki/Ad_libitum) web app inspired by [Mad Libs games](https://en.wikipedia.org/wiki/Mad_Libs)! Our own Madlibs app will have the following features:

* The app requires 5 nouns, 5 verbs, and 5 adjectives to generate a short, silly story.
* Words can be generated automatically through a provided Node [madlibs-api](https://github.com/kmaida/madlibs-api).
* Words can be typed in manually by the user.
* If the user's browser supports it, words can be entered through speech recognition using the computer's microphone.
* The app will then automatically fetch supplemental pronouns and use the user's words to generate and then display the story.

In Chrome, our app will look like this when it's finished:

![Madlibs app with Angular and speech recognition](https://images.ctfassets.net/23aumh6u8s0i/6W07LfYGGUdaJf2NVrcqHu/ad8d56f679900f1ba1d74648054b74c2/final-chrome)

> **Note:** In other browsers that don't support speech recognition, the "Speak to Play" feature will not be displayed. Users will still be able to generate words using the API or type them manually.

Though our Madlibs app is relatively small, it has a lot of features and robust functionality, so we'll build it over a short series of two tutorial articles.

> **Note:** This tutorial moves quickly over the core Angular concepts. It's recommended that you have some experience with Angular before tackling the Madlibs app. You can check out the [Angular Tour of Heroes tutorial](https://angular.io/tutorial) or my [Real-World Angular Series](https://auth0.com/blog/real-world-angular-series-part-1/) to learn about Angular in-depth before beginning this tutorial.

Let's get started!

## Dependencies and Setup

The first thing we need to do is install dependencies. You'll need:

* [Node.js](https://nodejs.org) with npm
* [Angular CLI](https://github.com/angular/angular-cli#installation) - follow the README instructions to install the CLI globally

You should also clone the [madlibs-api](https://github.com/kmaida/madlibs-api) to your local machine. Once installed, you can start the API server by running the following command from the project's root folder:

```bash
$ node server
```

The API will then be accessible in the browser at `http://localhost:8084/api` with the endpoints specified in the [madlibs-api README](https://github.com/kmaida/madlibs-api).

### Create a New Angular Project

We'll use the Angular CLI to generate a new Angular project. In a folder of your choosing, run the following command:

```bash
$ ng new madlibs --style=scss
```

A new Angular project called `madlibs` will be generated with SCSS support. To start the app's server, navigate into the new project folder and run the `serve` command like so:

```bash
$ cd madlibs
$ ng serve
```

The app will run at `http://localhost:4200` and should look something like this in the browser:

![new Angular app works](https://images.ctfassets.net/23aumh6u8s0i/V1G0tbxhMi7gAz04ptRjj/3828aec3fce492ee0bb0545b0a505909/app-works)

### Add Bootstrap and Annyang From CDN

We'll add [Bootstrap](https://v4-alpha.getbootstrap.com/) for CSS styling and [Annyang](https://github.com/TalAter/annyang) for speech recognition using CDNs.

> **Note:** This tutorial uses an alpha version of Bootstrap v4, latest available at the time of writing. If a newer v4 release is available at the time of reading, please feel free to upgrade and make changes as necessary to the CSS in your app.

Open your app's `index.html` file and add the following CDN links to the document `<head>`:

``` html  

<!doctype html>
<html lang="en">
<head>
  ...
  
  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.6/css/bootstrap.min.css" integrity="sha384-rwoIResjU2yc3z8GV/NPeZWAv56rSmLldC3R/AZzGRnGxQQKnKkoFVhFQhNUwEyJ" crossorigin="anonymous">
  
  <script src="//cdnjs.cloudflare.com/ajax/libs/annyang/2.6.0/annyang.min.js"></script>
  ...
```

We now have access to Bootstrap's styles and Annyang's Web Speech API helpers in our application. We're ready to start development!

RxJS Advanced Tutorial: Getting Started

RxJS Advanced Tutorial: Use the Madlibs API

RxJS Advanced Tutorial: Create a Web Speech Service

7752008352217db815996ab04aec46e6?s=80 avatar

7752008352217db815996ab04aec46e6?s=80

Matias Quaranta

Document your ASP.NET Core Web APIs with Swagger and auto-generate authenticated clients quickly and easily with Autorest.

ASP.NET Core APIs in the fast lane with Swagger and Autorest

6c0654e56c8c73ffee8f76fe03d18ccf?s=80 avatar

6c0654e56c8c73ffee8f76fe03d18ccf?s=80

Alex Sears

JSON Web Tokens (JWT) provide an easy way to add authentication to Ruby apps. Learn all about how to secure your Rack API!



Early on in my career, when I was a wee little junior dev, learning Ruby on Rails and looking to impress, I came across an issue that is all too common these days. How do I authenticate a request with an API when the consuming client is a browser? This is a problem that will need to be solved if you are building a single page application.  At the time, I thought a single numeric "API token" that was returned to the user when they logged in was enough. Looking back, I realize how dumb of a move this was. It's extremely insecure!

Recently, I have been reading that [JSON Web Tokens](https://auth0.com/learn/json-web-tokens/) (also written as JWTs and pronounced "jots") are the way to go when authenticating with an API. If you haven't heard of JWTs, check out [the website](https://jwt.io/) and [read this blog post on using them with APIs](https://auth0.com/blog/2014/12/02/using-json-web-tokens-as-api-keys/). They make authenticating a user securely very easy.

Today, we are going to explore using JWTs in a Ruby environment, specifically with Rack apps. This includes Rails and Sinatra applications. Let's get to it! Create a new directory for this project and move into it.

```
mkdir ruby-jwt-api
cd ruby-jwt-api
```

First, let's setup the basic API itself. Create a `Gemfile` with the following in it.

```
source "https://rubygems.org"

gem 'sinatra'
gem 'jwt'
gem 'json'
```

Then, run `bundle`. If you don't already have bundler installed, run `gem install bundler`. This will install the dependencies we need. Next we need to create our `config.ru` file to run our Sinatra application.  Put the following in a file called `config.ru`.

```
require File.expand_path '../main.rb', __FILE__

run Rack::URLMap.new({
  '/' => Public,
  '/api' => Api
})
```

Here we are loading a file called `main.rb` and then setting up a new Rack application and running it. We create the application this way so we can put our JWT protection on only the API routes and not the public routes. We are loading the file, but we haven't created it yet! Let's do that. Create a file called `main.rb` and put the following in it.

```
require 'json'
require 'jwt'
require 'sinatra/base'

class Api < Sinatra::Base

  def initialize
    super

    @accounts = {
      tomdelonge: 10000,
      markhoppus: 50000,
      travisbarker: 1000000000
    }
  end

  get '/money' do
    content_type :json
    { message: "Hello, World!" }.to_json
  end
end

class Public < Sinatra::Base

  def initialize
    super

    @logins = {
      tomdelonge: 'allthesmallthings',
      markhoppus: 'therockshow',
      travisbarker: 'whatsmyageagain'
    }
  end

  post '/login' do
    username = params[:username]
    password = params[:password]

    if @logins[username.to_sym] == password
      content_type :json
      { message: "You logged in. Yay you!" }.to_json
    else
      halt 401
    end
  end

end
```

This code sets up our two application routes. The only public route we have right now is `/login`. It authenticates a user based on a username and password. Currently, it just returns a confirmation message. This is where we will eventually return a JWT the user can use to authenticate with the API. The API only has one route for now also called `/money`. It returns a simple message now too. Notice, we have hardcoded the values for our users. Normally this would come from a database of some sort.

Run `rackup` on the command line to start the server. Here are what our responses look like if we hit each of these endpoints. We hit the login route and get a success...

![First successful hit to the server endpoint](https://images.ctfassets.net/23aumh6u8s0i/37oTdL3zyegFb024TeBDxY/9104f52d64e6fdf6f46e1a05f75a075e/first_successful_hit)

...hit the login route and get an error...

![First unsuccessful hit to the server endpoint](https://images.ctfassets.net/23aumh6u8s0i/7E72SbsOBfnwiv74PxQNWo/74cc17454812ac79cfbb64ee310dea60/first_unsuccessful_hit)

...and hit the `/api/money` route to make sure our routing works correctly.

![First Successful API Hit](https://images.ctfassets.net/23aumh6u8s0i/5mSTx6nuOTca2kOHhVY1EF/a0f1d9f115419ea560f24dadc16d322b/first_successful_api_hit)

Now that we know our endpoints are working, let's add authentication and authorization using JWTs. We need to make sure that when we log our user in, we return a JWT so the user can use it to authenticate in the future.

```
post '/login' do
  username = params[:username]
  password = params[:password]

  if @logins[username.to_sym] == password
    content_type :json
    { token: token(username) }.to_json
  else
    halt 401
  end
end

def token username
  JWT.encode payload(username), ENV['JWT_SECRET'], 'HS256'
end

def payload username
  {
    exp: Time.now.to_i + 60 * 60,
    iat: Time.now.to_i,
    iss: ENV['JWT_ISSUER'],
    scopes: ['add_money', 'remove_money', 'view_money'],
    user: {
      username: username
    }
  }
end
```

Let's analyze this. We have changed what happens on a successful login. We set the content type to JSON and then return a Hash that has the token in it.

The token is generated by calling the `token` method and passing it the username. `token` uses [the jwt gem](https://github.com/jwt/ruby-jwt) to create an encoded JWT. It takes the payload, the secret, and the algorithm we want to use to sign the token. Our `token` method calls another method we created called `payload` which simply returns a Hash that contains all the data we want in our token payload.

Some things to note about the payload. It has an expiration date, which will be verified later. We also give it an issuer that we can verify later, a set of scopes that this token allows a user to do, and some data about our user. A sample response would look like this.

Restart your server. Make sure to pass the environment variables to it when you run it like so.

```
JWT_SECRET=someawesomesecret JWT_ISSUER=moneyapi.com rackup
```

![Retrieving a Successful JSON Web Token](https://images.ctfassets.net/23aumh6u8s0i/53TJSyy6aNrVQ0HE46bSZI/14262f5c738be70af3d1b76438bdd223/successful_token)

We have our first token! Yay! Notice how I have passed two environment variables on the command line. It's a good practice to pass these sorts of values in environment variables to avoid hardcoding them in our source code. These variables are used when creating (and later validating) our tokens.

Now we need to create a piece of middleware that will validate our token and then add the scopes and user data from the token to the request environment. This will allow us to access this information in our API routes. Add the following to our `main.rb` file.

```
class JwtAuth

  def initialize app
    @app = app
  end

  def call env
    begin
      options = { algorithm: 'HS256', iss: ENV['JWT_ISSUER'] }
      bearer = env.fetch('HTTP_AUTHORIZATION', '').slice(7..-1)
      payload, header = JWT.decode bearer, ENV['JWT_SECRET'], true, options

      env[:scopes] = payload['scopes']
      env[:user] = payload['user']

      @app.call env
    rescue JWT::DecodeError
      [401, { 'Content-Type' => 'text/plain' }, ['A token must be passed.']]
    rescue JWT::ExpiredSignature
      [403, { 'Content-Type' => 'text/plain' }, ['The token has expired.']]
    rescue JWT::InvalidIssuerError
      [403, { 'Content-Type' => 'text/plain' }, ['The token does not have a valid issuer.']]
    rescue JWT::InvalidIatError
      [403, { 'Content-Type' => 'text/plain' }, ['The token does not have a valid "issued at" time.']]
    end
  end

end
```

This is a simple Rack middleware setup. In the `call` method, we get the `HTTP_AUTHORIZATION` value out of the environment hash, which represents the `Authorization` header in the request.  We use `fetch` so we get a string if `HTTP_AUTHORIZATION` doesn't exist and then use `slice` to prevent throwing an error if the string indexes we want don't exist. This will strip off the "Bearer: " part of the `Authorization` header. We then decode the JWT and add the scopes and user data to the environment hash. Lastly, we call the next part in our middleware stack and pass it our modified environment.

We have wrapped this code in a `begin, rescue`. This is because the `jwt` gem will throw different exceptions for each thing that may be wrong with it, such as the validation not passing. We catch each one and return a good error message for it.

Now that we have the data available on our request environment, let's use it in our API route.

```
class Api < Sinatra::Base

  use JwtAuth

  def initialize
    super

    @accounts = {
      tomdelonge: 10000,
      markhoppus: 50000,
      travisbarker: 1000000000
    }
  end

  get '/money' do
    scopes, user = request.env.values_at :scopes, :user
    username = user['username'].to_sym

    if scopes.include?('view_money') && @accounts.has_key?(username)
      content_type :json
      { money: @accounts[username] }.to_json
    else
      halt 403
    end
  end

end
```

Here, we initialize the class with some data, like we did with the `Public` class. Notice we `use JwtAuth` in this class. This is our way of including our token authentication middleware. This causes it to be run before the routes on this class are run. We then setup a `/money` route. This route grabs the scopes and user out of the environment. It then gets the username out of the user data. It checks to make sure this token has the `view_money` scope and that the username is a valid one in the data we have. If all this checks out, it returns the amount of money in the account. That's all there is to it.

![Hiting the Get Money route](https://images.ctfassets.net/23aumh6u8s0i/2hmmyaWekQu2TTSqsagON2/0ca839945394450177cb232ffa92bb9b/get_money)

We can use this same setup to add and remove money from these accounts.

```
post '/money' do
  scopes, user = request.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?('add_money') && @accounts.has_key?(username)
    amount = request[:amount]
    @accounts[username] += amount.to_i

    content_type :json
    { money: @accounts[username] }.to_json
  else
    halt 403
  end
end

delete '/money' do
  scopes, user = request.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?('remove_money') && @accounts.has_key?(username)
    amount = request[:amount]

    @accounts[username] -= amount.to_i
    if @accounts[username] < 0
      @accounts[username] = 0
    end

    content_type :json
    { money: @accounts[username] }.to_json
  else
    halt 403
  end
end
```

Here we are doing similar work as the previous route except we are sending `POST` and `DELETE` requests to add and remove money.  Our output would look like this when adding money...

![Adding Money using the API endpoint](https://images.ctfassets.net/23aumh6u8s0i/6cREs0pHtL5ghb0aT9QHMc/5c45ddd136e86614f197c0427bc3f501/add_money)

...and when removing money.

![Deleting Money using the API endpoint](https://images.ctfassets.net/23aumh6u8s0i/4AGDt3bC0dQJGI3PyRpD5F/94877eba401879712cac3e1765c5d579/delete_money)

As you can see, we can now use JWTs to add and remove money also. You may have noticed that we have some duplicated code here though. That's not good when we can prevent it! Luckily, we can. We can refactor our code like so.

```
get '/money' do
  process_request request, 'view_money' do |req, username|
    content_type :json
    { money: @accounts[username] }.to_json
  end
end

post '/money' do
  process_request request, 'add_money' do |req, username|
    amount = req[:amount]
    @accounts[username] += amount.to_i

    content_type :json
    { money: @accounts[username] }.to_json
  end
end

delete '/money' do
  process_request request, 'remove_money' do |req, username|
    amount = request[:amount]

    @accounts[username] -= amount.to_i
    if @accounts[username] < 0
      @accounts[username] = 0
    end

    content_type :json
    { money: @accounts[username] }.to_json
  end
end

def process_request req, scope
  scopes, user = req.env.values_at :scopes, :user
  username = user['username'].to_sym

  if scopes.include?(scope) && @accounts.has_key?(username)
    yield req, username
  else
    halt 403
  end
end
```

We have extracted the common code out into its own method and pass in the functionality for each route into the `process_request` method as a block.

That's all there is to it. We can now use our `JwtAuth` middleware anywhere we want to protect routes with JSON web tokens.

![Drop the mic](https://images.ctfassets.net/23aumh6u8s0i/71PTFQvHyCb4tSTO4bUwr8/611c9310a6b1713a01992f3eb6a2a142/giphy)

## What about Auth0?

[Auth0](https://auth0.com/) handles all this business of authenticating your users and creating JWTs so you can concentrate on building your application. There's even [a gem](https://github.com/auth0/ruby-auth0) that makes interacting with the Auth0 API so much easier. Let them handle the boring authentication while you build the next MyFaceTwiSterGram.

Wanna integrate Auth0 with RoR? Simple. The excellent writers over at Auth0 have you covered. They have written [extensive documentation](https://auth0.com/docs/quickstart/webapp/rails/) on how to do just that. It goes a little something like this.

### Add Omniauth and Auth0's strategy

Add the following to your `Gemfile` and run `bundle install`.

```
gem 'omniauth', '~> 1.3'
gem 'omniauth-auth0', '~> 1.4'
```

### Initialize Omniauth

Put the following in a file at `config/initializers/auth0.rb`, replacing the ALL_CAPS values with their actual values received when creating an application on the Auth0 dashboard.

```
Rails.application.config.middleware.use OmniAuth::Builder do
  provider(
    :auth0,
    'YOUR_CLIENT_ID',
    'YOUR_CLIENT_SECRET',
    'YOUR_NAMESPACE',
    callback_path: "/auth/auth0/callback"
  )
end
```

### Add the callback handler for Auth0

Use this command to create a controller to handle the Auth0 callback.

```
rails generate controller auth0 callback failure --skip-template-engine --skip-assets
```

In this newly-created file, add the logic to handle the success and failure of the callback.

```
class Auth0Controller < ApplicationController
  def callback
    # This stores all the user information that came from Auth0
    # and the IdP
    session[:userinfo] = request.env['omniauth.auth']

    # Redirect to the URL you want after successfull auth
    redirect_to '/dashboard'
  end

  def failure
    # show a failure page or redirect to an error page
    @error_msg = request.params['message']
  end
end
```

Also, replace the routes we created earlier with the following ones instead.

```
get "/auth/auth0/callback" => "auth0#callback"
get "/auth/failure" => "auth0#failure"
```

### Add the callback to Auth0's dashboard

You need to make sure you add the callback URL to the [Application Settings](https://manage.auth0.com/#/applications) in the Auth0 dashboard area.

For example, the callbacks we have created will be reached at `http://yourUrl/auth/auth0/callback`.

### Pick a method of triggering the login

There are multiple ways you can trigger the login flow in your application. For example, you could use the Auth0 Lock widget, Passwordless, or some custom UI. Here is what the code would look like to use the Lock widget in modal form.

```html
  <script src=“https://cdn.auth0.com/js/lock/10.0/lock.min.js"></script>
  <script type="text/javascript">

    var lock = new Auth0Lock('YOUR_CLIENT_ID', 'YOUR_NAMESPACE');


    function signin() {
      lock.show({
        callbackURL: '',
        responseType: 'code',
        authParams: {
          scope: 'openid email'  // Learn about scopes: https://auth0.com/docs/scopes
        }
      });
    }
  </script>
  <button onclick="window.signin();">Login</button>
```

### Accessing User Info

Once all this is setup, you can access user information like you normally would when using the Omniauth gem and its provider gems.

```ruby
class DashboardController < SecuredController
  def show
    @user = session[:userinfo]
  end
end
```

```html
  <div>
    <img class="avatar" src="<%= @user[:info][:image] %/>"/>
    <h2>Welcome <%= @user[:info][:name] %></h2>
  </div>
```

This is only a portion of the information you can get from their docs. [Head over there](https://auth0.com/docs/quickstart/webapp/rails) to get more information on integrating with Rails.

## Authentication is hard

Authentication in a web application can be difficult. However, whether you use Auth0 or roll your own solution, the `jwt` ruby gem offers a simple way to use JWTs in your ruby application. This allows stateless authentication that can be used in a traditional application or a decentralized API.

<include src="TweetQuote" quoteText="Authentication in a web application can be difficult. However, Auth0 simplifies it with JWTs."/>


Ruby Authentication: Secure Your Rack Application with JWT

ryan-chenkie

Ryan is a full-stack JavaScript developer and trainer who mainly works with React, Angular, Node, and GraphQL. He runs a consultancy where he builds apps for companies and also helps established dev teams with their modern JavaScript challenges.<br /><br />Ryan is a Google Developer Expert, the host of the Entrepreneurial Coder Podcast, the author of Securing Angular Applications, and an all-around fanatic about application security.

Developer

Ryan Chenkie

Learn how to implement a simple REST API with JWT Authentication in Rust using the Nickel.rs web framework and the MongoDB Rust Driver.

Build an API in Rust with JWT Authentication using Nickel.rs

Damian Schenkelman

Damian was one of Auth0's earliest employees. He loves building products for developers and taking things from 0 to 1.
<br><br>
He played key roles in implementing product features and growing the engineering organization in the early stages, and later on defining Auth0's architecture for scale and creating new products. Today he helps shape Auth0's long term strategy and leads Auth0Lab, a small and amazing team doing research and development of forward-looking products.
<br><br>
He spends his spare time with family, and friends, exercising, and catching up on all things NBA.

VP R&D (Auth0Lab)

Learn how to add JWT API keys to a DenyList so they are no longer valid.

**tl;dr**: If you understand why and how to support blacklisting JWTs, then skip to the [code](#impl).

In a [previous post](https://auth0.com/blog/2014/12/02/using-json-web-tokens-as-api-keys/), we proposed an approach to using [JSON Web Tokens](https://auth0.com/learn/json-web-tokens/) as API Keys, going over some of the benefits of doing so and also providing some examples based on our [API v2 scenarios](https://auth0.com/docs/apiv2). This post follows up by explaining an aspect that was not covered before: how to add JWT API keys to a DenyList so they are no longer valid.

If you need an in-depth introduction to **JSON Web Tokens**, check out the **free** ebook below.

<include src="ebook-ads/JwtHandbook" />

## A Real World Example
Let's for a second assume that GitHub used JSON Web Tokens as API Keys and one of them was accidentally published on the web. You would want to make sure an app can no longer access your information by revoking that token:

<a href="https://images.ctfassets.net/23aumh6u8s0i/3FcfGQTrWrTXz2L7aOrTQJ/4b7e1f65761e5d45e6613534b5cd953b/blacklist_token.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/3FcfGQTrWrTXz2L7aOrTQJ/4b7e1f65761e5d45e6613534b5cd953b/blacklist_token.png"/></a>

## Framing the Problem
Providing support for blacklisting JWTs poses the following questions:

1. How are JWTs individually identified?
2. Who should be able to revoke JWTs?
3. How are tokens revoked?
4. How do we avoid adding overhead?

This blog post aims to answer the previous questions by leveraging our experience from implementing this feature in our [API v2](https://docs.auth0.com/apiv2).



### 1. How are JWTs individually identified?

To revoke a JWT we need to be able to tell one token apart from another one. The JWT spec proposes the [`jti`](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#jtiDef) (JWT ID) as a means to identify a token. From the specification:
> The jti (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well.

As a quick reminder, this is how the claims section of one of our JWT API tokens looks like:
<a href="https://images.ctfassets.net/23aumh6u8s0i/42R0pKeDgBxWfnogCtEQnZ/75b06ae9b03c6121e8a0b9b39c21251f/jwt_blacklist_01.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/42R0pKeDgBxWfnogCtEQnZ/75b06ae9b03c6121e8a0b9b39c21251f/jwt_blacklist_01.png"/></a>

The tokens accepted by our API use the `aud` claim to determine the tenant for which the JWT is valid. If we use the `(aud, jti)` pair as the token's identifier then each tenant is in charge of guaranteeing that there's no duplication among their tokens.

Similarly, if a token does not include the `jti` claim we do not allow it to be revoked.

### 2. Who should be able to revoke JWTs?

If anyone could revoke our API keys then unfortunately they wouldn't be of much use. We need a way of restricting who can revoke a JWT.

<include src="TweetQuote" quoteText="If anyone could revoke our API keys then unfortunately they wouldn't be of much use."/>

The way we solved it in our API is by defining a specific scope (permission) that allows blacklisting tokens. If you generate a JWT like the one shown in the next figure you will be able to revoke JWTs:
<a href="https://images.ctfassets.net/23aumh6u8s0i/2tovQjfBsagwVFQAchw6JV/790bee0566e203e69fd071955369a456/jwt_blacklist_02.png" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/2tovQjfBsagwVFQAchw6JV/790bee0566e203e69fd071955369a456/jwt_blacklist_02.png"/></a>

> Notice the `blacklist` action nested inside the `scopes` object.

### 3. How are tokens revoked?

To blacklist/revoke a token, you need a JWT API key (referred to as `JWT_API_KEY`) like the one described in #2. With it you can issue a `POST` request to `/api/v2/blacklists/tokens` as shown below (new lines added for clarity):

```
curl -H "Authorization: Bearer {JWT_API_KEY}"
-X POST
-H "Content-Type: application/json"
-d '{"aud":"u6nnAxGVjbBd8etXjj554YKGAG5HuVrp","jti":"test-token"}'
https://login.auth0.com/api/v2/blacklists/tokens
```

The complete documentation for the endpoint is [here](https://auth0.com/docs/apiv2#!/blacklists/post_tokens) but basically you need to:

* Send the `aud` and `jti` claims of the JWT to revoke.
* Send the JWT with the permissions necessary to blacklist tokens in the **Authorization** header.

To get the revoked tokens you can issue a `GET` to `/api/v2/blacklists/tokens`. You can use the [docs](https://auth0.com/docs/apiv2#!/blacklists/get_tokens) to figure out the how.

### 4. How do we avoid adding overhead?
You might be thinking:

> Wasn't the whole point of using JWTs avoiding a DB query?

Well, that is a benefit, though hardly the _whole point_. There is a caveat though: that question only applies if you have an application with a single issuer, not a multi-tenant system.

If there is more than one tenant, you don't want all of them to share the same secret. You still have to perform a database query to map the `aud` claim to the required `secret`.

With that in mind, these are some of the optimizations that you can implement:

* **Optimization 1**: The aforementioned operation involves I/O so it can be performed in parallel with our query to verify if a token has been revoked.

  > Of course, you can also add a caching layer with a reasonable expiration time to avoid the DB trips altogether.

* **Optimization 2**: Skip the expiration check if the `jti` claim is not part of the JWT.

* **Optimization 3**: To reduce the size of the revoked tokens store you could automatically remove JWTs from it once their [`exp`](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#expDef) is reached (assuming there is one).

<a name="impl"></a>
## Implementation
We have shipped version 1.3.0 of the open source [express-jwt](https://github.com/auth0/express-jwt) with support for [multi-tenancy](https://github.com/auth0/express-jwt#multi-tenancy) and [blacklisted tokens](https://github.com/auth0/express-jwt#revoked-tokens). We also put together a [sample](https://github.com/auth0/multitenant-jwt-auth) that shows everything working together. The sample is based on our [API v2](https://docs.auth0.com/apiv2) implementation.

The following code snippets use show the core sample parts:

### Securing the endpoint
The first thing we have is an API that we would like to protect. The `express-jwt` middleware is configured by providing:

* `secret` - A function in charge of retrieving the secret.
* `isRevoked` - A function in charge of checking if a JWT is revoked.

```javascript
var expressJwt = require('express-jwt');
// to protect /api routes with JWTs
app.use('/api', expressJwt({
  secret: secretCallback,
  isRevoked: isRevokedCallback
}));
```

### Handling multi-tenancy
The implementation for the `secretCallback` function reads the backing data store to retrieve the secret for a tenant.  It caches the secrets using the tenant identifier as the cache key.

If the data layer provides an encrypted tenant secret, it needs to be decrypted before calling `done`.

```javascript
var LRU = require('lru-cache');

var secretsCache = LRU({ /* options */ });

var secretCallback = function(req, payload, done){
  var audience = payload.aud;
  var cachedSecret = secretsCache.get(audience);

  if (cachedSecret) { return done(null, cachedSecret); }

  data.getTenantByIdentifier(audience, function(err, tenant){
    if (err) { return done(err); }
    if (!tenant) { return done(new Error('missing_secret')); }

    var secret = utilities.decrypt(tenant.secret);
    secretsCache.set(audience, secret);
    done(null, secret);
  });
};
```

### Supporting revoked JWTs
Similarly, the `isRevokedCallback` implementation caches whether a token is revoked or not using the `(aud, jti)` pair as the cache key. It also skips the check in case the `jti` claim is not present.

```javascript
var jtiCache = LRU({ /* options */ });

var isRevokedCallback = function(req, payload, done){
  var tokenId = payload.jti;
  if (!tokenId){
    // if it does not have jti it cannot be revoked
    return done(null, false);
  }

  var tokenIdentifier = payload.aud + ':' + payload.jti;
  var blacklisted = jtiCache.get(tokenIdentifier);
  if (typeof blacklisted !== 'undefined') { return done(null, blacklisted); }

  data.getRevokedTokenByIdentifier(tokenIdentifier, function(err, token){
    if (err) { return done(err); }
    blacklisted = !!token;
    jtiCache.set(tokenIdentifier,blacklisted)
    return done(null, blacklisted);
  });
};
```

## Conclusion
Most of the aforementioned content applies to blacklisting JWTs in general, not just JWT API keys.

Hopefully this blog post has provided some useful ideas on how to tackle this problem.

If you have any comments or questions don't hesitate to post them!

You an also get involved in [express-jwt](https://github.com/auth0/express-jwt)!
<iframe src="https://ghbtns.com/github-btn.html?user=auth0&amp;repo=express-jwt&amp;type=star&amp;count=true" frameborder="0" scrolling="0" width="170px" height="20px"></iframe>

<include src="asides/Jwt" />

Adding JSON Web Token API Keys to a DenyList

Most APIs today use an API Key to authenticate legitimate clients. API Keys are very simple to use from the consumer perspective:  You get an API key from the

Most APIs today use an **API Key** to authenticate legitimate clients. **API Keys** are very simple to use from the consumer perspective:

1. You get an **API key** from the service (in essence a shared secret).
2. Add the key to an `Authorization` header.
3. Call the API.

It can't get simpler than that, but this approach has some limitations.

The last couple of months, we've been working on our [API v2](https://docs.auth0.com/apiv2). We wanted to share what we've learnt implementing a more powerful security model using [JSON Web Tokens](http://jwt.io).



Using a JSON Web Token offers many advantages:

* **Granular Security**: API Keys provide an all-or-nothing access. JSON Web Tokens can provide much finer grained control.
* **Homogenous Auth Architecture**: Today we use cookies, API keys, home grown SSO solutions, OAuth etc. Standardizing on JSON Web Tokens gives you an homogenous token format across the board.
* **Decentralized Issuance**: API keys depend on a central storage and a service to issue them. JSON Web Tokens can be "self-issued" or be completely externalized, opening interesting scenarios as we will see below.
* **OAuth2 Compliance**: OAuth2 uses an opaque token that relies on a central storage. You can return a stateless JWT instead, with the allowed scopes and expiration.
* **Debuggability**: API keys are opaque random strings. JSON Web Tokens can be inspected.
* **Expiration Control**: API keys usually don't expire unless you revoke them. JSON Web Tokens can (and often do) have an expiration.
* **Devices**: You can't put an API key that has full access on a device, because what is on a phone or tablet can easily be stolen. But you can put a JWT with the right set of permissions.

If you'd like an in-depth introduction to **JSON Web Tokens**, check out our **free** ebook below.

<include src="ebook-ads/JwtHandbook" />

## Granular Security

One of the most interesting benefits of using JWTs is the first one listed above. Back in the old days, when databases were at the center of our client-server applications, we could create users with specific permissions on the database:

<a href="https://images.ctfassets.net/23aumh6u8s0i/2paJRM6vdAq4RO2k6ypich/b960d3ab0c364b327b2d4a2f1afc66c4/permissions-sql" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/s9tyvnrUrUjg7i39zWBOn/db84bd0b3a904e879c3484841d34cd1a/permissions-sql.png"/></a>

_Remember this?_

APIs are becoming central pieces of our distributed systems architecture. They are now the "gatekeepers" of our data. But in contrast with what was available in databases, virtually all API keys provide all-or-nothing access. Readers will likely be familiar with the `scope` parameter of OAuth2 based systems that offers this finer grained consent to access.

There are many situations in which you want to keep the simplicity of an **API Key** but only for a subset of all possible API operations.

[GitHub acknowledged this requirement](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) and now provides a way of creating a token with the scopes you need (mimicking the OAuth2 consent):

![](https://images.ctfassets.net/23aumh6u8s0i/6fdGKpvxjgD7seKbyvjb9O/4d82a5cb332aa836d93cb7e3044b5707/token_scopes)

In the next section, we will go through the details of how this can be implemented.

### How to implement it?

We don't know how GitHub implemented it (they probably used Ruby), but we will use it as an example. Let's say we want to implement an endpoint in the API to **create new repos**. You could model this with the following **JSON Web Token** payload. If you provide any of those scopes, then you can create repos:

```
{
  iat: 1416929109, // when the token was issued (seconds since epoch)
  jti: "aa7f8d0a95c", // a unique id for this token (for revocation purposes)
  scopes: ["repo", "public_repo"]  // what capabilities this token has
}
```
_Look at this token in <a href="http://jwt.io?value=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MTY5MjkxMDksImp0aSI6ImFhN2Y4ZDBhOTVjIiwic2NvcGVzIjpbInJlcG8iLCJwdWJsaWNfcmVwbyJdfQ.XCEwpBGvOLma4TCoh36FU7XhUbcskygS81HE1uHLf0E" target="_blank">jwt.io</a>_

The API endpoint would simply check for the presence of the right **scope** atribute (this example is written in node.js but any language would work):

```
// intercept all calls to API and validae the token
app.use('/api', express_jwt({secret: SECRET, userProperty: 'token_payload'}));

// for POST /user/repo validate that there is a scope `repo` or `public_repo`
app.post('/api/user/repo',
        check_scopes(['repo', 'public_repo']),
        function(req, res, next) {
    // create a repo
    ....
});

```

Notice the `check_scopes` middleware on the `/api/user/repo` route. This is how the `check_scopes` function is implemented:

```
function check_scopes(scopes) {
  return function(req, res, next) {
    //
    // check if any of the scopes defined in the token,
    // is one of the scopes declared on check_scopes
    //
    var token = req.token_payload;
    for (var i =0; i<token.scopes.length; i++){
      for (var j=0; j<scopes.length; j++){
          if(scopes[j] === token.scopes[i]) return next();
      }
    }

    return res.send(401, 'insufficient scopes')
  }
}

```

> Notice that no one can change the scopes variables. JWTs are digitally signed, so its content cannot be tampered with.  

Documenting an API is equally important. What would be a good way for surfacing this on an API explorer?

For Auth0, we decided to build our own documentation using [swagger](http://swagger.io/). Since we are a multi-tenant system, each tenant has an API Key and Secret that is used to sign the token. As a developer, you mark which scopes you need and a token will be auto-generated. You can copy and paste it to [jwt.io](http://jwt.io) to see the structure (this is the __debuggable__ piece, by the way).

<a href="https://images.ctfassets.net/23aumh6u8s0i/33kBdPt5Hlzt2UEt0yoRQp/e7227bdb1d82dc16fed9a145dc64896b/api-explorer3" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/7uKm8Sq6OiHUEs5v9AoKT7/3550cf71dfa93c43bbd0eb2b2b2c2191/api-explorer3.gif"/></a>

Scopes required by each operation are clearly identified:

<a href="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2" target="_blank"><img src="https://images.ctfassets.net/23aumh6u8s0i/4FDPqZmzwJWGdg9YGSUcEf/5f6ecef62c9d7f3ae0f64edad904a3a1/api-scopes2"/></a>

Our token format is a bit different from the one in the example we showed for GitHub. The good thing about JWTs is that they can contain _any_ data structure:

```
{
  iat: 1416929061,
  jti: "802057ff9b5b4eb7fbb8856b6eb2cc5b",
  scopes: {
    users: {
      actions: ['read', 'create']
    },
    users_app_metadata: {
      actions: ['read', 'create']
    }
  }
}
```

The string representation of the scope is `read:users` but in the JSON Web Token, we are using a more structured representation (note the hierarchy), this allows us to be more consistent. It also allows us to have an easy way to extend it for other scenarios.

## Conclusion & Resources

We have shown a new way of securing APIs based on JSON Web Tokens. This approach has some interesting benefits, in particular around _granular security_. In future posts we will go over other aspects, starting with how to revoke tokens.

Below are some of the resources that we used in our node.js backend implementation:

* The [hapi.js](http://hapijs.com) framework to create the API.
* A [fork](https://github.com/auth0/hapi-auth-jwt) of [hapi-auth-jwt](https://github.com/ryanfitz/hapi-auth-jwt) with [support for multitenant apps](https://github.com/ryanfitz/hapi-auth-jwt/pull/10) to handle authentication with JWTs.
* The awesome [ratify](https://github.com/mac-/ratify) library to both validate API input using [JSON schemas](http://json-schema.org) and automatically generate [swagger](http://swagger.io/) from said schemas for our docs.
* Swagger's support for arbitrary [authorizations objects](https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#514-authorizations-object) and a slightly [customized swagger-ui template](https://github.com/swagger-api/swagger-ui#customize) to render the scopes per operation.

If you want to see an example of this working, you can check out our API v2: <https://docs.auth0.com/apiv2>

We would love to hear your thoughts about this approach!

[Discuss here](https://ask.auth0.com/t/using-json-web-tokens-as-api-keys/357)

<include src="asides/Jwt" />

"web api"