From 56d4495227b4263904d4c3d72420d82208cea478 Mon Sep 17 00:00:00 2001 From: Sean Williams Date: Fri, 2 Nov 2018 17:48:20 -0500 Subject: [PATCH 1/5] adding README --- extauth/README | 114 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 extauth/README diff --git a/extauth/README b/extauth/README new file mode 100644 index 0000000..77cd8fa --- /dev/null +++ b/extauth/README @@ -0,0 +1,114 @@ +# extauth plugin + +## Summary +The purpose of the extauth plugin is to allow customers to BYO-JWT or "bring your own JWT" to Edge Microgateway (EM). +Although Apigee provides a public certificate and can generate JWTs for you, we also want to allow customers that already have and IDP, which they use to manage developer identities, to be able to send those JWTs to the Edge Microgateway. In this case the Microgateway should validate your IDPs JWT using the public JWK endpoint, extract the client ID from the JWT and validate that client ID in the oauth plugin. + +## JWT & JWK +A JWT is a JSON Web Token that is encoded, URL-safe, JSON object that contains claims about a subject and it can be used for authentication and authorization. A JWK (JSON Web Key) is a JSON object that contains a set of keys that can be used to validate a JWT. + +View the following links to learn more about [JWTs](https://tools.ietf.org/html/rfc7519) and [JWKs](https://tools.ietf.org/html/rfc7517). + + +## When do I use this plugin? +You should answer Yes to all the questions below. + +1. Do you have your own IDP (Okta, Ping, etc. )? +2. Do you want Edge Microgateway to validate your IDP's JWTs? + +If you answered yes to the questions above, then you need to use this plugin. + +## Process Summary + +1. Your IDP will generate a JWT via a /token request. +2. You include that JWT on the request to Edge Microgateway. +3. The EM `extauth` plugin will validate the token using the public JWK endpoint. +4. EM will extract the client_id from the JWT. +5. EM will pass the client Id in the x-api-key header. +6. EM `oauth` plugin will validate the client Id +7. If the client Id is valid this it will forward the request to the backend. + +## Prerequisites +Please complete the following tasks before you use this plugin. + +1. Create a product, developer and developer app in Apigee Edge. Read our [documentation](https://docs.apigee.com/api-platform/microgateway/2.5.x/setting-and-configuring-edge-microgateway#part2createentitiesonapigeeedge) for details. + +2. Import the client Id into Apigee Edge with the following requests. The secret is optional. Then associate the Client Id to the Apigee product. + * [Create the client Id](https://apidocs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D/apps/%7Bapp_name%7D/keys/create) + * This will associate the Client Id to the Apigee product. [Add API Product to client Id](https://apidocs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D/apps/%7Bapp_name%7D/keys/%7Bconsumer_key%7D) + +## Plugin configuration properties +The following properties can be set in the `extauth` stanza in the Microgateway configuration file. + +```yaml +extauth: + publickey_url: "URL to your JWK endpoint" + client_id: "the property name in the JWT that contains the client Id" # defaults to client_id + iss: "This should be the same issuer that is included int the JWT." + exp: true # can be true or false, but defaults to true; use true to check for the expiry time and send an error if the token is expired. + sendErr: true # can be either true or false, but defaults to true; set this to false if you want the extauth plugin to send an error if the JWT is invalid. + keepAuthHeader: false # can be true or false; default is false; set this to true if you want to pass the Authorization header to the backend. +``` + +## Enable the plugin +In the EM configuration file (`org-env-config.yaml`) make sure that your plugin sequence is as shown below. + +```yaml +plugins: + sequence: + - extauth + - oauth + # other plugins can be listed here +``` + +## Configure the plugin +In the same configuration file you also need to configure the `extauth` plugin in the EM configuration file. + +**Notice that I set the `client_id` property to `sub`, because Okta JWTs include the client Id in the `sub` property.** + +```yaml +extauth: + publickey_url: "https://youridp.com/oauth2/default/v1/keys" + client_id: "sub" + iss: "https://youridp.com/oauth2/default" +``` + + +## Okta example +This is an example of how I used this plugin with JWTs generated by Okta. + +```yaml +... + +plugins: + sequence: + - extauth + - oauth + +... + +extauth: + publickey_url: "https://yourinstance.oktapreview.com/oauth2/default/v1/keys" + client_id: "sub" + iss: "https://yourinstance.oktapreview.com/oauth2/default" +``` + + +### Setup a Okta Authorization Server +[Documentation](https://developer.okta.com/authentication-guide/implementing-authentication/set-up-authz-server) + +### Okta Scopes +[Okta Scopes](https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1#whats-a-scope) +[Create custom Okta scope](https://developer.okta.com/authentication-guide/implementing-authentication/set-up-authz-server#create-scopes-optional) + +### Curl to generate an Okta JWT +```bash +curl --request POST \ + --url https://yourokta.oktapreview.com/oauth2/default/v1/token \ + --header 'accept: application/json' \ + -u 'clientId:secret' \ + --header 'accept: application/json' \ + --header 'cache-control: no-cache' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'grant_type=client_credentials&scope=customScope' + ``` From 5438c57c1b72015cefdc656f9c78bfb079a13b97 Mon Sep 17 00:00:00 2001 From: Sean Williams Date: Fri, 2 Nov 2018 17:50:34 -0500 Subject: [PATCH 2/5] Update README --- extauth/README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extauth/README b/extauth/README index 77cd8fa..213b8ec 100644 --- a/extauth/README +++ b/extauth/README @@ -1,4 +1,4 @@ -# extauth plugin +#extauth plugin ## Summary The purpose of the extauth plugin is to allow customers to BYO-JWT or "bring your own JWT" to Edge Microgateway (EM). From 70bef4b513c679c2d89899b5255dcfbea94e733a Mon Sep 17 00:00:00 2001 From: Sean Williams Date: Fri, 2 Nov 2018 17:50:50 -0500 Subject: [PATCH 3/5] Update README --- extauth/README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extauth/README b/extauth/README index 213b8ec..77cd8fa 100644 --- a/extauth/README +++ b/extauth/README @@ -1,4 +1,4 @@ -#extauth plugin +# extauth plugin ## Summary The purpose of the extauth plugin is to allow customers to BYO-JWT or "bring your own JWT" to Edge Microgateway (EM). From 42dd3b16d3a89d39abc33fa02edcdb71a452b995 Mon Sep 17 00:00:00 2001 From: Sean Williams Date: Fri, 2 Nov 2018 17:52:09 -0500 Subject: [PATCH 4/5] changed extension of readme to .md --- extauth/README | 114 ------------------------------------------------- 1 file changed, 114 deletions(-) delete mode 100644 extauth/README diff --git a/extauth/README b/extauth/README deleted file mode 100644 index 77cd8fa..0000000 --- a/extauth/README +++ /dev/null @@ -1,114 +0,0 @@ -# extauth plugin - -## Summary -The purpose of the extauth plugin is to allow customers to BYO-JWT or "bring your own JWT" to Edge Microgateway (EM). -Although Apigee provides a public certificate and can generate JWTs for you, we also want to allow customers that already have and IDP, which they use to manage developer identities, to be able to send those JWTs to the Edge Microgateway. In this case the Microgateway should validate your IDPs JWT using the public JWK endpoint, extract the client ID from the JWT and validate that client ID in the oauth plugin. - -## JWT & JWK -A JWT is a JSON Web Token that is encoded, URL-safe, JSON object that contains claims about a subject and it can be used for authentication and authorization. A JWK (JSON Web Key) is a JSON object that contains a set of keys that can be used to validate a JWT. - -View the following links to learn more about [JWTs](https://tools.ietf.org/html/rfc7519) and [JWKs](https://tools.ietf.org/html/rfc7517). - - -## When do I use this plugin? -You should answer Yes to all the questions below. - -1. Do you have your own IDP (Okta, Ping, etc. )? -2. Do you want Edge Microgateway to validate your IDP's JWTs? - -If you answered yes to the questions above, then you need to use this plugin. - -## Process Summary - -1. Your IDP will generate a JWT via a /token request. -2. You include that JWT on the request to Edge Microgateway. -3. The EM `extauth` plugin will validate the token using the public JWK endpoint. -4. EM will extract the client_id from the JWT. -5. EM will pass the client Id in the x-api-key header. -6. EM `oauth` plugin will validate the client Id -7. If the client Id is valid this it will forward the request to the backend. - -## Prerequisites -Please complete the following tasks before you use this plugin. - -1. Create a product, developer and developer app in Apigee Edge. Read our [documentation](https://docs.apigee.com/api-platform/microgateway/2.5.x/setting-and-configuring-edge-microgateway#part2createentitiesonapigeeedge) for details. - -2. Import the client Id into Apigee Edge with the following requests. The secret is optional. Then associate the Client Id to the Apigee product. - * [Create the client Id](https://apidocs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D/apps/%7Bapp_name%7D/keys/create) - * This will associate the Client Id to the Apigee product. [Add API Product to client Id](https://apidocs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D/apps/%7Bapp_name%7D/keys/%7Bconsumer_key%7D) - -## Plugin configuration properties -The following properties can be set in the `extauth` stanza in the Microgateway configuration file. - -```yaml -extauth: - publickey_url: "URL to your JWK endpoint" - client_id: "the property name in the JWT that contains the client Id" # defaults to client_id - iss: "This should be the same issuer that is included int the JWT." - exp: true # can be true or false, but defaults to true; use true to check for the expiry time and send an error if the token is expired. - sendErr: true # can be either true or false, but defaults to true; set this to false if you want the extauth plugin to send an error if the JWT is invalid. - keepAuthHeader: false # can be true or false; default is false; set this to true if you want to pass the Authorization header to the backend. -``` - -## Enable the plugin -In the EM configuration file (`org-env-config.yaml`) make sure that your plugin sequence is as shown below. - -```yaml -plugins: - sequence: - - extauth - - oauth - # other plugins can be listed here -``` - -## Configure the plugin -In the same configuration file you also need to configure the `extauth` plugin in the EM configuration file. - -**Notice that I set the `client_id` property to `sub`, because Okta JWTs include the client Id in the `sub` property.** - -```yaml -extauth: - publickey_url: "https://youridp.com/oauth2/default/v1/keys" - client_id: "sub" - iss: "https://youridp.com/oauth2/default" -``` - - -## Okta example -This is an example of how I used this plugin with JWTs generated by Okta. - -```yaml -... - -plugins: - sequence: - - extauth - - oauth - -... - -extauth: - publickey_url: "https://yourinstance.oktapreview.com/oauth2/default/v1/keys" - client_id: "sub" - iss: "https://yourinstance.oktapreview.com/oauth2/default" -``` - - -### Setup a Okta Authorization Server -[Documentation](https://developer.okta.com/authentication-guide/implementing-authentication/set-up-authz-server) - -### Okta Scopes -[Okta Scopes](https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1#whats-a-scope) -[Create custom Okta scope](https://developer.okta.com/authentication-guide/implementing-authentication/set-up-authz-server#create-scopes-optional) - -### Curl to generate an Okta JWT -```bash -curl --request POST \ - --url https://yourokta.oktapreview.com/oauth2/default/v1/token \ - --header 'accept: application/json' \ - -u 'clientId:secret' \ - --header 'accept: application/json' \ - --header 'cache-control: no-cache' \ - --header 'content-type: application/x-www-form-urlencoded' \ - --data 'grant_type=client_credentials&scope=customScope' - ``` From 386ae47186babbe366473fe72074cf45ff203316 Mon Sep 17 00:00:00 2001 From: Sean Williams Date: Fri, 2 Nov 2018 17:53:10 -0500 Subject: [PATCH 5/5] changed README file extension. --- extauth/README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 extauth/README.md diff --git a/extauth/README.md b/extauth/README.md new file mode 100644 index 0000000..77cd8fa --- /dev/null +++ b/extauth/README.md @@ -0,0 +1,114 @@ +# extauth plugin + +## Summary +The purpose of the extauth plugin is to allow customers to BYO-JWT or "bring your own JWT" to Edge Microgateway (EM). +Although Apigee provides a public certificate and can generate JWTs for you, we also want to allow customers that already have and IDP, which they use to manage developer identities, to be able to send those JWTs to the Edge Microgateway. In this case the Microgateway should validate your IDPs JWT using the public JWK endpoint, extract the client ID from the JWT and validate that client ID in the oauth plugin. + +## JWT & JWK +A JWT is a JSON Web Token that is encoded, URL-safe, JSON object that contains claims about a subject and it can be used for authentication and authorization. A JWK (JSON Web Key) is a JSON object that contains a set of keys that can be used to validate a JWT. + +View the following links to learn more about [JWTs](https://tools.ietf.org/html/rfc7519) and [JWKs](https://tools.ietf.org/html/rfc7517). + + +## When do I use this plugin? +You should answer Yes to all the questions below. + +1. Do you have your own IDP (Okta, Ping, etc. )? +2. Do you want Edge Microgateway to validate your IDP's JWTs? + +If you answered yes to the questions above, then you need to use this plugin. + +## Process Summary + +1. Your IDP will generate a JWT via a /token request. +2. You include that JWT on the request to Edge Microgateway. +3. The EM `extauth` plugin will validate the token using the public JWK endpoint. +4. EM will extract the client_id from the JWT. +5. EM will pass the client Id in the x-api-key header. +6. EM `oauth` plugin will validate the client Id +7. If the client Id is valid this it will forward the request to the backend. + +## Prerequisites +Please complete the following tasks before you use this plugin. + +1. Create a product, developer and developer app in Apigee Edge. Read our [documentation](https://docs.apigee.com/api-platform/microgateway/2.5.x/setting-and-configuring-edge-microgateway#part2createentitiesonapigeeedge) for details. + +2. Import the client Id into Apigee Edge with the following requests. The secret is optional. Then associate the Client Id to the Apigee product. + * [Create the client Id](https://apidocs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D/apps/%7Bapp_name%7D/keys/create) + * This will associate the Client Id to the Apigee product. [Add API Product to client Id](https://apidocs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email_or_id%7D/apps/%7Bapp_name%7D/keys/%7Bconsumer_key%7D) + +## Plugin configuration properties +The following properties can be set in the `extauth` stanza in the Microgateway configuration file. + +```yaml +extauth: + publickey_url: "URL to your JWK endpoint" + client_id: "the property name in the JWT that contains the client Id" # defaults to client_id + iss: "This should be the same issuer that is included int the JWT." + exp: true # can be true or false, but defaults to true; use true to check for the expiry time and send an error if the token is expired. + sendErr: true # can be either true or false, but defaults to true; set this to false if you want the extauth plugin to send an error if the JWT is invalid. + keepAuthHeader: false # can be true or false; default is false; set this to true if you want to pass the Authorization header to the backend. +``` + +## Enable the plugin +In the EM configuration file (`org-env-config.yaml`) make sure that your plugin sequence is as shown below. + +```yaml +plugins: + sequence: + - extauth + - oauth + # other plugins can be listed here +``` + +## Configure the plugin +In the same configuration file you also need to configure the `extauth` plugin in the EM configuration file. + +**Notice that I set the `client_id` property to `sub`, because Okta JWTs include the client Id in the `sub` property.** + +```yaml +extauth: + publickey_url: "https://youridp.com/oauth2/default/v1/keys" + client_id: "sub" + iss: "https://youridp.com/oauth2/default" +``` + + +## Okta example +This is an example of how I used this plugin with JWTs generated by Okta. + +```yaml +... + +plugins: + sequence: + - extauth + - oauth + +... + +extauth: + publickey_url: "https://yourinstance.oktapreview.com/oauth2/default/v1/keys" + client_id: "sub" + iss: "https://yourinstance.oktapreview.com/oauth2/default" +``` + + +### Setup a Okta Authorization Server +[Documentation](https://developer.okta.com/authentication-guide/implementing-authentication/set-up-authz-server) + +### Okta Scopes +[Okta Scopes](https://developer.okta.com/blog/2017/07/25/oidc-primer-part-1#whats-a-scope) +[Create custom Okta scope](https://developer.okta.com/authentication-guide/implementing-authentication/set-up-authz-server#create-scopes-optional) + +### Curl to generate an Okta JWT +```bash +curl --request POST \ + --url https://yourokta.oktapreview.com/oauth2/default/v1/token \ + --header 'accept: application/json' \ + -u 'clientId:secret' \ + --header 'accept: application/json' \ + --header 'cache-control: no-cache' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data 'grant_type=client_credentials&scope=customScope' + ```