Skip to content

Commit

Permalink
Add quick start to README
Browse files Browse the repository at this point in the history
  • Loading branch information
Rajith90 committed May 13, 2019
1 parent 0c945c7 commit 578bf0b
Show file tree
Hide file tree
Showing 4 changed files with 356 additions and 1 deletion.
71 changes: 71 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ WSO2 API Microgateway acts as a proxy that is capable of performing security val
* [Project Structure](#project-structure)
* [How to run the microgateway distribution](#how-to-run-the-microgateway-distribution)
* [Invoke API exposed via microgateway](#invoke-api-exposed-via-microgateway)
* [Micro gateway quick start](#micro-gateway-quick-start)
* [Micro gateway supported open API extensions](#micro-gateway-supported-open-api-extensions)
* [Micro gateway open API extension usages](#micro-gateway-open-api-extension-usages)
* [1. Override endpoint per API resource](#1-override-endpoint-per-api-resource)
Expand Down Expand Up @@ -211,6 +212,43 @@ curl -X GET "https://localhost:9095/petstore/v1/pet/findByStatus?status=availabl
Please note that the jwt provided in the command is a jwt toke retrieved from WSO2 API Manager with higher expiry time which can be used with any API not protected with scopes.
This token works with any API because, default microgateway config uses the public certificate of WSO2 API Manager to validate the signature.

#### Micro gateway quick start
Lets see how we can expose pet store API using microgatway with the open API definition

1. First download the microgateway toolkit related to latest release from product [release page](https://github.com/wso2/product-microgateway/releases)

1. Then extract the toolkit and navigate to the /bin folder of the toolkit.

1. Now lets create the project with name "petstore-project"
```
./micro-gw init petstore-project
```

4. Now the project is initialized. There will be directory with name "petstore-project" in the location where we executed the command.
Lets copy the [open API definition](samples/petstore_basic.yaml) to the **api_definitions** directory inside the project.

1. Lets execute the following command to build the project.
```
./micro-gw build petstore-project
```
Executable file will be created inside the target folder of the project.

6. Lets run the executable file using the micro gateway runtime docker image
```
docker run -d -v <PROJECT_TARGET_PATH>:/home/exec/ -p 9095:9095 -p 9090:9090 -e project="petstore-project" wso2/wso2micro-gw:3.0.0-beta2
<PROJECT_TARGET_PATH> - The path of the target directoy created inside the project directory
```
this will expose https endpoint with port 9095 and the context of the API will be as "/petstore/v1"

7. Lets invoke the API with below commands
```
curl -X GET "https://localhost:9095/petstore/v1/pet/findByStatus?status=available" -H "accept: application/xml" -H "Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==" -k
curl -X GET "https://localhost:9095/petstore/v1/pet/1" -H "accept: application/xml" -H "Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UQXhabU14TkRNeVpEZzNNVFUxWkdNME16RXpPREpoWldJNE5ETmxaRFUxT0dGa05qRmlNUSJ9.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbiIsImFwcGxpY2F0aW9uIjp7ImlkIjoyLCJuYW1lIjoiSldUX0FQUCIsInRpZXIiOiJVbmxpbWl0ZWQiLCJvd25lciI6ImFkbWluIn0sInNjb3BlIjoiYW1fYXBwbGljYXRpb25fc2NvcGUgZGVmYXVsdCIsImlzcyI6Imh0dHBzOlwvXC9sb2NhbGhvc3Q6OTQ0M1wvb2F1dGgyXC90b2tlbiIsImtleXR5cGUiOiJQUk9EVUNUSU9OIiwic3Vic2NyaWJlZEFQSXMiOltdLCJjb25zdW1lcktleSI6Ilg5TGJ1bm9oODNLcDhLUFAxbFNfcXF5QnRjY2EiLCJleHAiOjM3MDMzOTIzNTMsImlhdCI6MTU1NTkwODcwNjk2MSwianRpIjoiMjI0MTMxYzQtM2Q2MS00MjZkLTgyNzktOWYyYzg5MWI4MmEzIn0=.b_0E0ohoWpmX5C-M1fSYTkT9X4FN--_n7-bEdhC3YoEEk6v8So6gVsTe3gxC0VjdkwVyNPSFX6FFvJavsUvzTkq528mserS3ch-TFLYiquuzeaKAPrnsFMh0Hop6CFMOOiYGInWKSKPgI-VOBtKb1pJLEa3HvIxT-69X9CyAkwajJVssmo0rvn95IJLoiNiqzH8r7PRRgV_iu305WAT3cymtejVWH9dhaXqENwu879EVNFF9udMRlG4l57qa2AaeyrEguAyVtibAsO0Hd-DFy5MW14S6XSkZsis8aHHYBlcBhpy2RqcP51xRog12zOb-WcROy6uvhuCsv-hje_41WQ==" -k
```

### Micro gateway supported open API extensions
| Extension | Description | Required/Not Required |
| ------------- | ------------- | ----------------------|
Expand Down Expand Up @@ -480,3 +518,36 @@ So the complete command for the above sample is like
```
bash gateway -e myEndpoint3_prod_endpoint_0=<new back end url>
```

### Micro gateway securing APIs.
The gateway supports the "securitySchemes" keyword in open API specifications.
Currently micro gateway supports oauth2 and basic authentication for APIs which can be defined via open API extensions.
If none of the securitySchemes are defined the gateway by default applies oauth2 security.

1. Define scopes for the resources and API using oauth2 security type.
```
securityDefinitions:
petstore_auth:
type: oauth2
authorizationUrl: 'https://petstore.swagger.io/oauth/authorize'
flow: implicit
scopes:
'write:pets': modify pets in your account
'read:pets': read your pets
```

We can define oauth2 security type, and add scopes and refer the security scheme in API level or resource level

```
security:
- petstore_auth:
- 'write:pets'
- 'read:pets'
```

2. Define basic authentication for the API
```
securityDefinitions:
petstore_basic:
type: basic
```
5 changes: 4 additions & 1 deletion docker/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,7 @@
FROM ballerina/ballerina-runtime:0.990.4
LABEL maintainer="dev@wso2.org"

COPY runtime/ /ballerina/runtime/bre/lib/
COPY runtime/ /ballerina/runtime/bre/lib/
ADD conf/ /home/ballerina/conf/

CMD ballerina run --config /home/ballerina/conf/micro-gw.conf /home/exec/${project}.balx
90 changes: 90 additions & 0 deletions docker/conf/micro-gw.conf
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
[listenerConfig]
host="0.0.0.0"
httpPort=9090
httpsPort=9095
keyStore.path="${ballerina.home}/bre/security/ballerinaKeystore.p12"
keyStore.password="ballerina"
trustStore.path="${ballerina.home}/bre/security/ballerinaTruststore.p12"
trustStore.password="ballerina"
tokenListenerPort=9096

[authConfig]
authorizationHeader="Authorization"
removeAuthHeaderFromOutMessage=true

[keyManager]
serverUrl="https://localhost:9443"
username="admin"
password="admin"
tokenContext="oauth2"
timestampSkew=5000
verifyHostname=true

[jwtTokenConfig]
issuer="https://localhost:9443/oauth2/token"
audience="http://org.wso2.apimgt/gateway"
certificateAlias="wso2apim"


[jwtConfig]
header="X-JWT-Assertion"

[caching]
enabled=true
tokenCache.expiryTime=900000
tokenCache.capacity=10000
tokenCache.evictionFactor=0.25

[analytics]
enable=false
uploadingTimeSpanInMillis=600000
uploadingEndpoint="https://localhost:9444/analytics/v1.0/usage/upload-file"
rotatingPeriod=600000
task.uploadFiles=true
username="admin"
password="admin"
verifyHostname=true

[http2]
enable=false

[mutualSSLConfig]
protocolName="TLS"
protocolVersions="TLSv1.2,TLSv1.1"
ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_DSS_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ,TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 ,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,TLS_EMPTY_RENEGOTIATION_INFO_SCSV"
sslVerifyClient="not_require"

["b7a.users"]
["b7a.users.generalUser1"]
password="5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8"

[validationConfig]
enableRequestValidation = false
enableResponseValidation = false
absolutePathToSwagger = " "


[throttlingConfig]
enabledGlobalTMEventPublishing = false
jmsConnectioninitialContextFactory = "bmbInitialContextFactory"
jmsConnectionProviderUrl= "amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672'"
jmsConnectionUsername = ""
jmsConnectionPassword = ""
throttleEndpointUrl = "https://localhost:9443/endpoints"
verifyHostname=true
throttleEndpointbase64Header = "admin:admin"

[tokenRevocationConfig]
[tokenRevocationConfig.realtime]
enableRealtimeMessageRetrieval = false
jmsConnectionTopic = "tokenRevocation"
jmsConnectioninitialContextFactory = "bmbInitialContextFactory"
jmsConnectionProviderUrl= "amqp://admin:admin@carbon/carbon?brokerlist='tcp://localhost:5672'"
jmsConnectionUsername = ""
jmsConnectionPassword = ""
[tokenRevocationConfig.persistent]
enablePersistentStorageRetrieval = false
useDefault = true
hostname = "https://127.0.0.1:2379/v2/keys/jti/"
username = "root"
password = "root"
191 changes: 191 additions & 0 deletions samples/security_sample.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
---
openapi: 3.0.0
servers:
- url: https://petstore.swagger.io/v2
- url: http://petstore.swagger.io/v2
info:
description: 'This is a sample server Petstore server. You can find out more about
Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For
this sample, you can use the api key `special-key` to test the authorization filters.'
version: 1.0.0
title: Swagger Petstore New
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
- name: pet
description: Everything about your Pets
externalDocs:
description: Find out more
url: http://swagger.io
- name: store
description: Access to Petstore orders
- name: user
description: Operations about user
externalDocs:
description: Find out more about our store
url: http://swagger.io
x-mgw-basePath: /petstore/v1
x-mgw-production-endpoints:
urls:
- https://petstore.swagger.io/v2
paths:
"/pet/findByStatus":
get:
tags:
- pet
summary: Finds Pets by status
description: Multiple status values can be provided with comma separated strings
operationId: findPetsByStatus
parameters:
- name: status
in: query
description: Status values that need to be considered for filter
required: true
explode: true
schema:
type: array
items:
type: string
enum:
- available
- pending
- sold
default: available
responses:
'200':
description: successful operation
content:
application/xml:
schema:
type: array
items:
"$ref": "#/components/schemas/Pet"
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/Pet"
'400':
description: Invalid status value
"/pet/{petId}":
get:
tags:
- pet
summary: Find pet by ID
description: Returns a single pet
operationId: getPetById
parameters:
- name: petId
in: path
description: ID of pet to return
required: true
schema:
type: integer
format: int64
security:
- OAuth2:
- read
- write
responses:
'200':
description: successful operation
content:
application/xml:
schema:
"$ref": "#/components/schemas/Pet"
application/json:
schema:
"$ref": "#/components/schemas/Pet"
'400':
description: Invalid ID supplied
'404':
description: Pet not found
components:
schemas:
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: Category
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: Tag
Pet:
type: object
required:
- name
- photoUrls
properties:
id:
type: integer
format: int64
category:
"$ref": "#/components/schemas/Category"
name:
type: string
example: doggie
photoUrls:
type: array
xml:
name: photoUrl
wrapped: true
items:
type: string
tags:
type: array
xml:
name: tag
wrapped: true
items:
"$ref": "#/components/schemas/Tag"
status:
type: string
description: pet status in the store
enum:
- available
- pending
- sold
xml:
name: Pet
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
read: Grants read access
write: Grants write access
admin: Grants access to admin operations
mybasic:
type: basic
requestBodies:
Pet:
content:
application/json:
schema:
"$ref": "#/components/schemas/Pet"
application/xml:
schema:
"$ref": "#/components/schemas/Pet"
description: Pet object that needs to be added to the store
required: true


0 comments on commit 578bf0b

Please sign in to comment.