https://github.com/danielpetisme/jhipster-quarkus-okta-sample

https://github.com/danielpetisme/jhipster-quarkus-okta-sample

Last synced: 5 days ago
JSON representation

• Host: GitHub
• URL: https://github.com/danielpetisme/jhipster-quarkus-okta-sample
• Owner: danielpetisme
• Created: 2021-03-02T22:42:33.000Z (over 3 years ago)
• Default Branch: master
• Last Pushed: 2021-03-02T23:21:34.000Z (over 3 years ago)
• Last Synced: 2024-10-19T21:18:46.579Z (28 days ago)
• Language: TypeScript
• Size: 606 KB
• Stars: 0
• Watchers: 2
• Forks: 5
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# jhipster

This application was generated using JHipster 6.10.5 and JHipster Quarkus 1.0.0, you can find documentation and help at [https://www.jhipster.tech/documentation-archive/v6.10.5](https://www.jhipster.tech/documentation-archive/v6.10.5).

## Development

Before you can build this project, you must install and configure the following dependencies on your machine:

1. [Node.js][]: We use Node to run a development web server and build the project.

   Depending on your system, you can install Node either from source or as a pre-packaged bundle.

After installing Node, you should be able to run the following command to install development tools.

You will only need to run this command when dependencies change in [package.json](package.json).

    npm install

We use npm scripts and [Webpack][] as our build system.

Run the following commands in two separate terminals to create a blissful development experience where your browser

auto-refreshes when files change on your hard drive.

    ./mvnw

    npm start

Npm is also used to manage CSS and JavaScript dependencies used in this application. You can upgrade dependencies by

specifying a newer version in [package.json](package.json). You can also run `npm update` and `npm install` to manage dependencies.

Add the `help` flag on any command to see how you can use it. For example, `npm help update`.

The `npm run` command will list all of the scripts available to run for this project.

## OAuth 2.0 / OpenID Connect

Congratulations! You've selected an excellent way to secure your JHipster application. If you're not sure what OAuth and OpenID Connect (OIDC) are, please see [What the Heck is OAuth?](https://developer.okta.com/blog/2017/06/21/what-the-heck-is-oauth)

To log in to your app, you'll need to have [Keycloak](https://keycloak.org) up and running. The JHipster Team has created a Docker container for you that has the default users and roles. Start Keycloak using the following command.

```

docker-compose -f src/main/docker/keycloak.yml up

```

The security settings in `src/main/resources/application.properties` are configured for this image.

```properties

quarkus.oidc.enabled=true

quarkus.oidc.auth-server-url=http://localhost:9080/auth/realms/jhipster/

quarkus.oidc.client-id=web_app

quarkus.oidc.credentials.secret=web_app

quarkus.oidc.authentication.scopes=profile,address,email,address,phone,offline_access

quarkus.oidc.application-type=hybrid

quarkus.oidc.authentication.cookie-path=/

quarkus.oidc.authentication.redirect-path=/login/oauth2/code/oidc

quarkus.oidc.authentication.restore-path-after-redirect=false

jhipster.oidc.logout-url=http://localhost:9080/auth/realms/jhipster/protocol/openid-connect/logout

```

### Okta

If you'd like to use Okta instead of Keycloak, it's pretty quick using the [Okta CLI](https://cli.okta.com/). After you've installed it, run:

```shell

okta register

```

Then, in your JHipster app's directory, run `okta apps create` and select **JHipster**.

This will set up an Okta app for you, create `ROLE_ADMIN` and `ROLE_USER` groups, create a `.okta.env` file with your Okta settings, and configure a `groups` claim in your ID token.

Note: As for now, in a JHipster context, the generated `.okta.env` is Spring oriented.

```shell

cat .okta.env

export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET="{clientSecret}"

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI="{yourOktaDomain}"

export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID="{clientId}"

```

You can use the above environment variables in your `src/main/resources/application.properties` (or copy/paste the Okta settings values).

```properties

quarkus.oidc.auth-server-url=${SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI}

quarkus.oidc.client-id=${SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID}

quarkus.oidc.credentials.secret=${SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET)

jhipster.oidc.logout-url=https://{yourOktaDomain}/oauth2/default/v1/logout

```

Run `source .okta.env` and start your app with Maven or Gradle. You should be able to sign in with the credentials you registered with.

If you're on Windows, you should install [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) so the `source` command will work.

If you'd like to configure things manually through the Okta developer console, see the instructions below.

First, you'll need to create a free developer account at . After doing so, you'll get your own Okta domain, that has a name like `https://dev-123456.okta.com`.

Modify `src/main/resources/application.properties` to use your Okta settings.

```properties

quarkus.oidc.auth-server-url=https://{yourOktaDomain}/oauth2/default

quarkus.oidc.client-id={clientId}

quarkus.oidc.credentials.secret={clientSecret}

jhipster.oidc.logout-url=https://{yourOktaDomain}/oauth2/default/v1/logout

```

Create an OIDC App in Okta to get a `{clientId}` and `{clientSecret}`. To do this, log in to your Okta Developer account and navigate to **Applications** > **Add Application**. Click **Web** and click the **Next** button. Give the app a name you’ll remember, specify `http://localhost:8080` as a Base URI, and `http://localhost:8080/login/oauth2/code/oidc` as a Login Redirect URI. Click **Done**, then Edit and add `http://localhost:8080` as a Logout redirect URI. Copy and paste the client ID and secret into your `application.properties` file.

Create a `ROLE_ADMIN` and `ROLE_USER` group and add users into them. Modify e2e tests to use this account when running integration tests. You'll need to change credentials in `src/test/javascript/e2e/account/account.spec.ts` and `src/test/javascript/e2e/admin/administration.spec.ts`.

Navigate to **API** > **Authorization Servers**, click the **Authorization Servers** tab and edit the default one. Click the **Claims** tab and **Add Claim**. Name it "groups", and include it in the ID Token. Set the value type to "Groups" and set the filter to be a Regex of `.*`.

After making these changes, you should be good to go! If you have any issues, please post them to [Stack Overflow](https://stackoverflow.com/questions/tagged/jhipster). Make sure to tag your question with "jhipster" and "okta".

### PWA Support

JHipster ships with PWA (Progressive Web App) support, and it's turned off by default. One of the main components of a PWA is a service worker.

The service worker initialization code is commented out by default. To enable it, uncomment the following code in `src/main/webapp/index.html`:

```html

  if ('serviceWorker' in navigator) {

    navigator.serviceWorker.register('./service-worker.js').then(function () {

      console.log('Service Worker Registered');

    });

  }

```

Note: [Workbox](https://developers.google.com/web/tools/workbox/) powers JHipster's service worker. It dynamically generates the `service-worker.js` file.

### Managing dependencies

For example, to add [Leaflet][] library as a runtime dependency of your application, you would run following command:

    npm install --save --save-exact leaflet

To benefit from TypeScript type definitions from [DefinitelyTyped][] repository in development, you would run following command:

    npm install --save-dev --save-exact @types/leaflet

Then you would import the JS and CSS files specified in library's installation instructions so that [Webpack][] knows about them:

Edit [src/main/webapp/app/vendor.ts](src/main/webapp/app/vendor.ts) file:

```

import 'leaflet/dist/leaflet.js';

```

Edit [src/main/webapp/content/scss/vendor.scss](src/main/webapp/content/scss/vendor.scss) file:

```

@import '~leaflet/dist/leaflet.css';

```

Note: There are still a few other things remaining to do for Leaflet that we won't detail here.

For further instructions on how to develop with JHipster, have a look at [Using JHipster in development][].

### Using Angular CLI

You can also use [Angular CLI][] to generate some custom client code.

For example, the following command:

    ng generate component my-component

will generate few files:

    create src/main/webapp/app/my-component/my-component.component.html

    create src/main/webapp/app/my-component/my-component.component.ts

    update src/main/webapp/app/app.module.ts

## Building for production

### Packaging as thin jar

To build the final jar and optimize the jhipster application for production, run:

```

./mvnw -Pprod clean package

```

This will concatenate and minify the client CSS and JavaScript files. It will also modify `index.html` so it references these new files.

To ensure everything worked, run:

    java -jar target/*.jar

Then navigate to [http://localhost:8080](http://localhost:8080) in your browser.

Refer to [Using JHipster in production][] for more details.

### Packaging as native executable

_Targeting your Operation System_

In order to build a native image locally, your need to have [GraalVM](https://www.graalvm.org/) installed and `GRAALVM_HOME` defined.

You can use the `native` profile as follow to build native executable.

```

./mvnw package -Pnative

```

Keep in mind that the generated native executable is dependent on your Operating System.

_Targeting a container environment_

If you plan to run your application in a container, run:

```

./mvnw package -Dnative -Dquarkus.native.container-build=true

```

It will use a Docker container with GraalVM installed and produce an 64 bit Linux executable.

## Testing

To launch your application's tests, run:

    ./mvnw verify

### Client tests

Unit tests are run by [Jest][] and written with [Jasmine][]. They're located in [src/test/javascript/](src/test/javascript/) and can be run with:

    npm test

For more information, refer to the [Running tests page][].

## Using Docker to simplify development (optional)

You can use Docker to improve your JHipster development experience. A number of docker-compose configuration are available in the [src/main/docker](src/main/docker) folder to launch required third party services.

For example, to start a mysql database in a docker container, run:

    docker-compose -f src/main/docker/mysql.yml up -d

To stop it and remove the container, run:

    docker-compose -f src/main/docker/mysql.yml down

[jhipster homepage and latest documentation]: https://www.jhipster.tech

[jhipster 6.10.5 archive]: https://www.jhipster.tech/documentation-archive/v6.10.5

[using jhipster in development]: https://www.jhipster.tech/documentation-archive/v6.10.5/development/

[using docker and docker-compose]: https://www.jhipster.tech/documentation-archive/v6.10.5/docker-compose

[using jhipster in production]: https://www.jhipster.tech/documentation-archive/v6.10.5/production/

[running tests page]: https://www.jhipster.tech/documentation-archive/v6.10.5/running-tests/

[code quality page]: https://www.jhipster.tech/documentation-archive/v6.10.5/code-quality/

[setting up continuous integration]: https://www.jhipster.tech/documentation-archive/v6.10.5/setting-up-ci/

[node.js]: https://nodejs.org/

[yarn]: https://yarnpkg.org/

[webpack]: https://webpack.github.io/

[angular cli]: https://cli.angular.io/

[browsersync]: https://www.browsersync.io/

[jest]: https://facebook.github.io/jest/

[jasmine]: https://jasmine.github.io/2.0/introduction.html

[protractor]: https://angular.github.io/protractor/

[leaflet]: https://leafletjs.com/

[definitelytyped]: https://definitelytyped.org/