Archived

WeCarry has been discontinued and will not be developed further

Welcome to the WeCarry.App server code!

Requirements

This software needs docker-compose version 1.24.0 at least.

Setting it up

In an appropriate directory:

• git clone git@github.com: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.encrypted file, the proper settings based on the local-example.env file)

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.

Installation Troubleshooting

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/

Authentication

Auth Request Error Codes

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.

Organization Authentication

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.

Office365/AzureAD

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.)

Google GSuite

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.)

SAML

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

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.

Facebook

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

Google can be used as a social authentication as well as an org-based authentication method. See the Google section above for configuration details.

Microsoft

The two environment variables MICROSOFT_KEY and MICROSOFT_SECRET will need to be set for a Microsoft developer account.

LinkedIn

The two environment variables LINKED_IN_KEY and LINKED_IN_SECRET will need to be set for the appropriate LinkedIn oauth developer account.

Twitter (Dicey Auth Option)

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.

REST API Documentation

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.

API

API Documentation

Coming soon

Conventions

Implicit null vs explicit `null

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.

TLS / HTTPS

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.

Automated Jobs

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