Improve documentation for CompositeProviderFlag

[trentjeff]

The javadoc https://helidon.io/docs/v2/apidocs/io.helidon.security/io/helidon/security/CompositeProviderFlag offers very little guidance in helping users choose the appropriate configuration when composite providers are configured.

One recent question from slack has the user configuring two providers: (1) OID, with a fallback of (@) Basic-Auth. The user was configuring both providers as "MAY_FAIL". However, the appropriate configuration should be having both configured as "SUFFICIENT" with optional flag set to true.

This configuration, however, is entirely not obvious from reading the documentation. We should therefore improve the documentation - probably by providing examples for when/how it is appropriate for using compositions that include MAY_FAIL, SUFFICIENT, and optional=true - as well as the other flags available.

Also related to this is considering how the OID provider was not available due to a network outage (or perhaps a 404). We should also mention this case in particular to indicate something like "a failure to reach the security provider" will be treated as a failure, etc.

bad:

security:
  enabled: true
  provider-policy:
    type: "COMPOSITE"
    name: "composite-policy"
    default: true
    authentication:
      - name: "basic-authenticator"
        flag: "MAY_FAIL"
      - name: "oidc-authenticator"
        flag: "MAY_FAIL"
  providers:
  - name: "basic-authenticator"
    http-basic-auth:
      realm: "helidon"
      users:
      - login: "uimuser"
        password: "changeit"
  - name: "oidc-authenticator"
    oidc:
      identity-uri: "http://ohs1.oamdomain.org:30305"
      base-scopes: "FedRserver.Info"
      client-id: topologyClient
      client-secret: Welcome1
      token-endpoint-auth: CLIENT_SECRET_POST
      cookie-name: "OIDC_SESSION"
      cookie-same-site: "Lax"
      header-use: true
      audience: "FedRserver"
      redirect: true
      redirect-uri: "/sr/test/sol005Adapter"

Good (partially; needs optional: true for oidc):

security:
  enabled: true
  provider-policy:
    type: "COMPOSITE"
    name: "composite-policy"
    default: true
    authentication:
      - name: "basic-authenticator"
        flag: "SUFFICIENT"
      - name: "oidc-authenticator"
        flag: "SUFFICIENT"