WeCarry has been discontinued and will not be developed further
This software needs docker-compose version 1.24.0 at least.
In an appropriate directory:
-
git clone [email protected]:silinternational/wecarry-api.git
-
cd wecarry-api
-
cp local-example.env local.env
-
give the entries in local.env the appropriate values
(note that for deployment to the cloud, you need to provide, e.g. via an
.env.encryptedfile, the proper settings based on thelocal-example.envfile)
In application/grifts, copy private.go.example to private.go and correct the example values.
- make
Note that the data provided in .env.example will not allow
all features to work.
The fake AWS data will work for file uploads to the minIO
container, but obviously not for a real AWS S3 bucket.
Default versions which come with your operating system may have earlier versions of these installed.
Make sure to uninstall docker-compose packages, and then following the instructions here: https://docs.docker.com/compose/install/
When an auth request is made to the wecarry api and something goes wrong, the api will render json with a Code entry for the error. To see a list of possible codes, refer to domain/errorcodes.go. In particular, the related codes are those that have a comment referring to actions.AuthRequest.
Three types of authentication can be used for organization-based authentication: Azure AD, Google, and SAML. These are configured in an Organization record or an Organization Domain record, and are supported by the REST API.
To add an organization using AzureAD authentication, create a database organization record
that includes an auth_type of AZUREADV2 and an auth_config like the following ...
{
"TenantID": "12345678-abcd-1234-871a-940bc318789c",
"ClientSecret": "nice and crazy complicated secret :-)",
"ApplicationID": "12345678-abcd-1234-92f6-fffe9f3dfc6d"
}
For local development, if you are using http, then you will need to
use http:localhost as the host for the WeCarry API, due to AzureAD's policies.
(This affects the AUTH_CALLBACK_URL in the .env file and the buffalo.environment.HOST value
in the docker-compose file.)
To add an organization using Google authentication, create a database organization record
that includes an auth_type of GOOGLE and an auth_config like the following ...
{}
The two environment variables GOOGLE_KEY and GOOGLE_SECRET will need to be
set for the appropriate Google oauth developer account.
To learn about requirements on the Google side, start here
At this point, Google does not allow *.local domains to access their oauth2 api.
So, for local development, your api's host should probably just be localhost
(It may also be the case that using buffalo dev will require the use of localhost to avoid
losing track of the google related session during authentication.)
To enable authentication via a SAML2 Identity Provider, an organization
record will need to be created that includes an auth_type of SAML and an
auth_config like the following ...
{
"SPEntityID": "http://example.local:3000",
"AudienceURI": "http://example.local:3000",
"IDPEntityID": "our.idp.net",
"SignRequest": true,
"AttributeMap": null,
"SPPrivateKey": "-----BEGIN PRIVATE KEY-----\nMIIG/gIB...OJxmEMBgT\n-----END PRIVATE KEY-----\n",
"SPPublicCert": "-----BEGIN CERTIFICATE-----\nMIIEXTCC...xmvKt42A=\n-----END CERTIFICATE-----\n",
"IDPPublicCert": "-----BEGIN CERTIFICATE-----\nMIIDXTC...2bb\nPw==\n-----END CERTIFICATE-----",
"SingleLogoutURL": "https://our.idp.net/saml2/idp/SingleLogoutService.php",
"SingleSignOnURL": "https://our.idp.net/saml2/idp/SSOService.php",
"CheckResponseSigning": true,
"RequireEncryptedAssertion": false,
"AssertionConsumerServiceURL": "http://example.local:3000/auth/callback"
}
Social network authentication is used only for authenticating users that are not associated with a subscribing Organization, but have been invited to a WeCarry Event.
The two environment variables FACEBOOK_KEY and FACEBOOK_SECRET
will need to be set for the appropriate Facebook oauth account and application.
For local development, if you are using http, then you will likely need to
use http:localhost as the host for the WeCarry API, due to Facebook's policies.
(This affects the AUTH_CALLBACK_URL in the .env file and the buffalo.environment.HOST value
in the docker-compose file.)
Google can be used as a social authentication as well as an org-based authentication method. See the Google section above for configuration details.
The two environment variables MICROSOFT_KEY and MICROSOFT_SECRET will need
to be set for a Microsoft developer account.
The two environment variables LINKED_IN_KEY and LINKED_IN_SECRET will need to be
set for the appropriate LinkedIn oauth developer account.
The two environment variables TWITTER_KEY and TWITTER_SECRET will need to be
set for the appropriate LinkedIn oauth developer account.
The problem with Twitter is that its users don't necessarily have a separate First Name and Last Name. We added a function that either uses a space or underscore as the separator (based on the User.Name) or just duplicates the User.Name as both the First and Last Names.
The source of this application is annotated with special annotations for go-swagger to use to generate a Swagger specification file as well as render it as HTML.
To generate the swagger spec swagger/swagger.json run make swagger.
Coming soon
The standard established for this API is both implicit null (field
omitted from json) and explicit null (null specified in json)
will erase or set to null. The reference UI
implementation, wecarry-ui,
will always include all supported fields.
WeCarry API can either run with HTTPS/TLS or standard HTTP. If running behind a load balancer that terminates SSL/TLS connections for you, using HTTPS/TLS in the container as well may not be necessary, but if possible it's a good idea.
TLS is used by default but can be disabled by setting DISABLE_TLS=true in the environment.
When TLS is used, WeCarry API generates a self-signed certificate and provides it upon request.
Certain automated jobs can be triggered via a POST http call to the /service endpoint.
A companion project includes lambda functions for calling that endpoint.
You can find it at https://github.com/silinternational/wecarry-lambdas