edit-icon download-icon

OpenID Connect authorization

Last Updated: Dec 28, 2017

OpenID Connect is a lightweight standard based on OAuth 2.0, which provides a framework for identity interaction through APIs. Compared with OAuth, OpenID Connect not only authenticates a request, but also specifies the identity of the requester.

Based on OpenID Connect, the API gateway provides two way to authenticate API request:

  • OpenID Connect

    Comply with standard OpenID Connect, the API customer request a “Token” through “userLoginName” and “password” first.And the API gateway performs Token verification on the request when the customer call the API.

  • OpenID Connect & AlibabaCloudAPP

    Based on OpenID Connect, the API gateway performs Appkey+Token verification on the request and authenticates the Appkey and Token. The system of the API provider issues the Token and the gateway issues the Appkey.

The difference between the OpenID Connect and OpenID Connect & AlibabaCloudApp: OpenID Connect & Alibaba cloud App needs to authenticate APPkey, and OpenID Connect does not.

Functions that are not supported by OpenID Connect

  • Cannot use App authentication
  • Cannot use App level Throttling
  • Cannot use AlibabaCloud Account level Throttling

Implementation principle

By performing OpenID Connect authentication, APIs can be classified into authorization APIs and service APIs.
1

2

  • Authorization APIs: Interfaces used to issue a Token to the client. When configuring such APIs, you must inform the API gateway about the key corresponding to your Token and the public key used to resolve the Token.
  • Service APIs: Interfaces used to obtain user information and perform an operation. When configuring such APIs, you must inform the API gateway about the parameter that represents the Token in your request. After the request arrives at the API gateway, the API gateway automatically checks whether this request is valid.

Certification method

  1. The client calls an authorization API

    1. The client uses authentications to get the “Token”:

      • OpenID Connect

        The client uses userLoginName/password to call an authorization API to obtain authorization Token.

      • OpenID Connect & AlibabaCloudAPP

        The client uses your Appkey signature+user name/password to call an authorization API to obtain authorization Token.

    2. After receiving the request, the API gateway authenticates your Appkey first(Be effect on OpenID Connect & AlibabaCloudAPP, and OpenID Connect not). If the authentication succeeds, the API gateway calls the account system of the backend service to authenticate your user name/password.

    3. After the authentication by the backend service succeeds, you can use the returned Token to call a service API.

  2. The client calls a service API

    1. The client uses the Token obtained by the authorization API and the signed Appkey to call the service API.

    2. The API gateway authenticates and resolves the Token and sends the user information contained in the Token to the backend.

    3. During this phase, the API provider must follow these steps in advance:

      1. Opens the account system, allows the API gateway to authenticate the user name/password in the request, and issues the Token based on the gateway-provided encryption mode. For more information, see How to implement the AS module as follows.
      2. Defines the API in the API gateway. For more information, see Configure an API in the API gateway as follows.
        NOTE: The user name/password is extremely sensitive information, which is risky when being transmitted in plaintext. We recommend that you encrypt the user name/password and use the HTTPS protocol for transmission.

Solution

The solution includes two important parts:

1. Authorization server (AS): Used to generate the id_token and manage the KeyPair.

You must perform this step by yourself. For more information about the method, see Configure an API in the API gateway as follows.
3

As shown in the preceding figure, the process is as follows:

  1. The Consumer (caller) sends an id_token authentication request to the API gateway, for example, in the user name+password (U+P) mode.
  2. The API gateway transparently transmits the request to the AS.
  3. The AS sends the user authentication request to the Provider (service provider).
  4. The Provider returns the authentication results or an error message if the authentication fails.
  5. If the authentication succeeds, the AS generates an id_token, which includes the User information (expandable, and can include other necessary information).
  6. The API gateway sends the id_token returned by the AS to the Consumer.

    Note: The AS is not required to be independently deployed. It can be integrated in the Provider and used to generate the id_token in the entire system. The generated id_token must meet the Specification in the OIDC protocol (version 1.0).

2. Resource server (RS): Used to verify the id_token and resolve corresponding information.

This part is implemented by the gateway. Because the RS function has been integrated in the API gateway, the Provider only needs to generate the id_token in compliance with the corresponding encryption rules.
4

As shown in the preceding figure, the process is as follows:

  1. The Consumer sends the parameter with the id_token to the API gateway.
  2. The API gateway saves the publicKey used for verification, verifies and resolves the id_token to obtain the User information, and sends the User information to the Provider. If the authentication fails, the API gateway returns an error message.
  3. The Provider processes the request and returns the results to the API gateway.
  4. The API gateway transparently transmits the results from the Provider to the Consumer.

NOTE: The RS serves as the Consumer of the id_token. The request can be forwarded to the Provider only when the id_token verification succeeds.

How to implement the AS module

Use the OIDC in the AS to generate the id_token

  • The id_token, also known as ID Token, is a type of tokens defined in the OIDC protocol. For more information, see OpenID Connect Core 1.0.
  • The KeyPair, keyId, and Claims are required to generate the id_token (for more information about the Claims, see ID_Token).

KeyId description

The KeyId must be unique. For example, the KeyId generated using the UUID is a string of at least 32 random characters, which can be all numbers or numbers and letters.
Example (Java)

  1. String keyId = UUID.randomUUID().toString().replaceAll("-", "");
Or
  1. String keyId = String.valueOf(UUID.randomUUID().getMostSignificantBits()) + String.valueOf(UUID.randomUUID().getMostSignificantBits());

KeyPair description

The KeyPair is a PKI system-based public and private key pair using the asymmetric algorithm. Each pair contains a publicKey and a privateKey. The publicKey is stored in the RS, which is used for verification. The privateKey is stored in the AS, which serves as the digital signature when the id_token is generated.
The KeyPair uses the RSA SHA256 encryption algorithm. To guarantee security, 2,048 bits are encrypted.
All KeyPairs used in the AS are in the JSON format. The following is an example:
publicKey:

  1. {"kty":"RSA","kid":"67174182967979709913950471789226181721","alg":"ES256","n":"oH5WunqaqIopfOFBz9RfBVVIIcmk0WDJagAcROKFiLJScQ8N\_nrexgbCMlu-dSCUWq7XMnp1ZSqw-XBS2-XEy4W4l2Q7rx3qDWY0cP8pY83hqxTZ6-8GErJm\_0yOzR4WO4plIVVWt96-mxn3ZgK8kmaeotkS0zS0pYMb4EEOxFFnGFqjCThuO2pimF0imxiEWw5WCdREz1v8RW72WdEfLpTLJEOpP1FsFyG3OIDbTYOqowD1YQEf5Nk2TqN\_7pYrGRKsK3BPpw4s9aXHbGrpwsCRwYbKYbmeJst8MQ4AgcorE3NPmp-E6RxA5jLQ4axXrwC0T458LIVhypWhDqejUw","e":"AQAB"}
privateKey:
  1. {"kty":"RSA","kid":"67174182967979709913950471789226181721","alg":"ES256","n":"oH5WunqaqIopfOFBz9RfBVVIIcmk0WDJagAcROKFiLJScQ8N\_nrexgbCMlu-dSCUWq7XMnp1ZSqw-XBS2-XEy4W4l2Q7rx3qDWY0cP8pY83hqxTZ6-8GErJm\_0yOzR4WO4plIVVWt96-mxn3ZgK8kmaeotkS0zS0pYMb4EEOxFFnGFqjCThuO2pimF0imxiEWw5WCdREz1v8RW72WdEfLpTLJEOpP1FsFyG3OIDbTYOqowD1YQEf5Nk2TqN\_7pYrGRKsK3BPpw4s9aXHbGrpwsCRwYbKYbmeJst8MQ4AgcorE3NPmp-E6RxA5jLQ4axXrwC0T458LIVhypWhDqejUw","e":"AQAB","d":"aQsHnLnOK-1xxghw2KP5JTZyJZsiwt-ENFqqJfPUzmlYSCNAV4T39chKpkch2utd7hRtSN6Zo4NTnY8EzGQQb9yvunaiEbWUkPyJ6kM3RdlkkGLvVtp0sRwPCZ2EAYBlsMad9jkyrtmdC0rtf9jerzt3LMLC7XWbnpC3WAl8rsRDR1CGs\_-u4sfZfttsaUbJDD9hD0q4NfLDCVOZoQ\_8wkZxyWDAQGCe6GcCbu6N81fTp2CSVbiBj7DST\_4x2NYUA2KG8vyZYcwviNTxQzk4iPfdN2YQz\_9aMTZmmhVUGlmTvAjE5ebBqcqKAS0NfhOQHg2uR46eBKBy\_OyVOLohsQ","p":"8Tdo3DCs-0t9JMtM0lYqPRP4wYJs37Rv6S-ygRui2MI\_hadTY9I2A199JMYw7Fjke\_wa3gqJLa98pbybdLWkrOxXbKEkwE4uc4-fuNjLbUTC5tqdM5-nXmpL887uREVYnk8FUzvWeXYTCNCb7OLw5l8yPJ1tR8aNcd0fJNDKh98","q":"qlRrGSTsZzBkDgDi1xlCoYvoM76cbmxrCUK-mc\_kBRHfMjlHosxFUnAbxqIBE4eAJEKVfIJLQrHFvIDjQb3kM9ylmwMCu9f8u9DHrT8J7LSDlLqDaXuiM2oiKtW3bAaBPuiR7sVMFcuB5baCebHU487YymJCBTfeCZtFdi6c4w0","dp":"gVCROKonsjiQCG-s6X4j-saAL016jJsw-7QEYE6uiMHqR\_6iJ\_uD1V8Vuec-RxaItyc6SBsh24oeqsNoG7Ndaw7w912UVDwVjwJKQFCJDjU0v4oniItosKcPvM8M0TDUB1qZojuMCWWRYsJjNSWcvAQA7JoBAd-h6I8AqT39tcU","dq":"BckMQjRg2zhnjZo2Gjw\_aSFJZ8iHo7CHCi98LdlD03BB9oC\_kCYEDMLGDr8d7j3h-llQnoQGbmN\_ZeGy1l7Oy3wpG9TEWQEDEpYK0jWb7rBK79hN8l1CqyBlvLK5oi-uYCaiHkwRQ4RACz9huyRxKLOz5VvlBixZnFXrzBHVPlk","qi":"M5NCVjSegf\_KP8kQLAudXUZi\_6X8T-owtsG\_gB9xYVGnCsbHW8gccRocOY1Xa0KMotTWJl1AskCu-TZhOJmrdeGpvkdulwmbIcnjA\_Fgflp4lAj4TCWmtRI6982hnC3XP2e-nf\_z2XsPNiuOactY7W042D\_cajyyX\_tBEJaGOXM"}

Example of generating a KeyPair (Java)

  1. import java.security.PrivateKey;
  2.  
  3. import org.jose4j.json.JsonUtil;
  4. import org.jose4j.jwk.RsaJsonWebKey;
  5. import org.jose4j.jwk.RsaJwkGenerator;
  6. import org.jose4j.jws.AlgorithmIdentifiers;
  7. import org.jose4j.jws.JsonWebSignature;
  8. import org.jose4j.jwt.JwtClaims;
  9. import org.jose4j.jwt.NumericDate;
  10. import org.jose4j.lang.JoseException;
  1. String keyId = UUID.randomUUID().toString().replaceAll("-", "");
  2. RsaJsonWebKey jwk = RsaJwkGenerator.generateJwk(2048);
  3. jwk.setKeyId(keyId);
  4. jwk.setAlgorithm(AlgorithmIdentifiers.ECDSA_USING_P256_CURVE_AND_SHA256);
  5. String publicKey = jwk.toJson(RsaJsonWebKey.OutputControlLevel.PUBLIC_ONLY);
  6. String privateKey = jwk.toJson(RsaJsonWebKey.OutputControlLevel.INCLUDE_PRIVATE);

Process for generating an id_token

  1. Use the Claims attributes (aud, sub, exp, iat, and iss) defined in the OIDC protocol and the attribute values to generate the Claims (the full name is JwtClaims).

    Code example (Java)

    1. JwtClaims claims = new JwtClaims();
    2. claims.setGeneratedJwtId();
    3. claims.setIssuedAtToNow();
    4. //expire time
    5. NumericDate date = NumericDate.now();
    6. date.addSeconds(120);
    7. claims.setExpirationTime(date);
    8. claims.setNotBeforeMinutesInThePast(1);
    9. claims.setSubject("YOUR_SUBJECT");
    10. claims.setAudience("YOUR_AUDIENCE");
    11. //Add custom parameters
    12. claims.setClaim(key, value);
  2. Use the keyId, Claims, privateKey, and the digital signature algorithm (RSA SHA256) to generate a JSON Web Signature (JWS).

    Code example (Java)

    1. JsonWebSignature jws = new JsonWebSignature();
    2. jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256);
    3. jws.setKeyIdHeaderValue(keyId);
    4. jws.setPayload(claims.toJson());
    5. PrivateKey privateKey = new RsaJsonWebKey(JsonUtil.parseJson(privateKeyText)).getPrivateKey();
    6. jws.setKey(privateKey);
  3. Use the JWS to obtain the value of the id_token.

    Code example (Java)

    1. String idToken = jws.getCompactSerialization();

    Example of a generated id_token:

    1. eyJhbGciOiJSUzI1NiIsImtpZCI6Ijg4NDgzNzI3NTU2OTI5MzI2NzAzMzA5OTA0MzUxMTg1ODE1NDg5In0.eyJ1c2VySWQiOiIzMzcwMTU0NDA2ODI1OTY4NjI3IiwidGFnTmFtZSI6ImNvbmFuVGVzdCIsImV4cCI6MTQ4MDU5Njg3OSwiYXVkIjoiQWxpX0FQSV9Vc2VyIiwianRpIjoiTm9DMFVVeW5xV0N0RUFEVjNoeEIydyIsImlhdCI6MTQ4MDU5MzI3OSwibmJmIjoxNDgwNTkzMjE5LCJzdWIiOiJ7ZGF0YU1hcD0ne3VzZXJJZD0zMzcwMTU0NDA2ODI1OTY4NjI3fScsIHN0YXR1c0NvZGU9JzAnLCBlcnJvcnM9J1tdJ30ifQ.V3rU2VCziSt6uTgdCktYRsIwkMEMsO_jUHNCCIW_Sp4qQ5ExjtwNt9h9mTGKFRujk2z1E0k36smWf9PbNGTZTWmSYN8rvcQqdsupcC6LU9r8jreA1Rw1CmmeWY4HsfBfeInr1wCFrEfZl6_QOtf3raKSK9AowhzEsnYRKAYuc297gmV8qlQdevAwU75qtg8j8ii3hZpJqTX67EteNCHZfhXn8wJjckl5sHz2xPPyMqj8CGRQ1wrZEHjUmNPw-unrUkt6neM0UrSqcjlrQ25L8PEL2TNs7nGVdl6iS7Nasbj8fsERMKcZbP2RFzOZfKJuaivD306cJIpQwxfS1u2bew

Configure an API in the API gateway

  1. In the API edition function, the OpenID Connect option is added to Security certification of Basic Info. The Alibaba Cloud App certification method is also included, which means that only authorized apps can call this API.

    5

  2. After selecting OpenID Connect for Security certification, set OpenID Connect mode. The following two options are provided.
    6

    1. Authorization APIs: Used to obtain the Token, for example, obtaining the Token using U+P.
    2. Service APIs: Used by the Provider to provide services. The Consumer calls the obtained Token as an input parameter.
      The OpenID Connect certification method is used for the preceding two types of APIs. The following section describes how to configure these two types of APIs, respectively.
  3. For the authorization APIs, you must configure the KeyId and publicKey, as shown in the following figure.
    7

    KeyId: A unique ID corresponding to the KeyPair, which is generated by the AS. For example:

    1. 88483727556929326703309904351185815489
    publicKey: Used to verify and resolve the Token, which is generated by the AS. For example:

    1. {"kty":"RSA","kid":"88483727556929326703309904351185815489","alg":"ES256","n":"ie0IKvKLd7Y3izHcZemdDsVVXg5QtWtGF7XEkILnn66R2\_3a30DikqV409OVL7Hv0ElACgCaBLEgZeGHTcdLE1xxDTna8MMBnBNuMVghvFERCKh8uzpxlQsfcnFd5IFdJWj1x5Tscetrow6lA3h5zYx0rF5TkZzC4DclxgDmITRam0dsHBxr3uk9m9YYBz2mX0ehjY0px7vIo7hZH2J3gODEPorIZkk3x8GPdlaA4P9OFAO4au9-zcVQop9vLirxdwDedk2p-F9GP6UiQC9V2LTWqkVw\_oPBf9Rlh8Qdi19jA8SeCfzAxJZYlbOTK8dYAFAVEFsvXCFvdaxQefwWFw","e":"AQAB"}

    Configurations of other parameters are the same as those for common APIs, which are not described.

    No matter creating an API or modifying an API, the configured KeyId and publicKey take effect only after the API is released.

  4. For the service APIs, you must configure the parameter corresponding to the Token.

    8

    1. As shown in the preceding figure, the parameter corresponding to the Token is that sent to the id_token when the Consumer calls the API. The API gateway identifies, verifies, and resolves this parameter.

    2. In the Input parameter definition area, a corresponding parameter must be defined. Otherwise, an error message is prompted, as shown in the following figure.9

    3. Configuring the custom system parameters: The service API enables configuration of custom system parameters on the Define API backend server tab. One example is shown in the following figure.
      10If the id_token generated by the AS contains the userId of the Consumer, the userId resolved from the id_token sent by the Consumer is transmitted to the Provider. The configuration method for custom system parameters is similar to that for system parameters.
      Besides the preceding three aspects, the method for defining other configurations of the API is the same as that in the preceding sections, which are not described.
Thank you! We've received your feedback.